Get Spotify artist and search data

"Spotify API" is a crowded search. The official Web API is Spotify's. This page is the other job: read public catalog fields (an artist, a track, a search page) through SocialScrape, with the same key you use for TikTok or YouTube. It does not mint Spotify credentials. It does not upload audio. It is in beta.

Authenticate with x-api-key. See authentication.

Find the id#

Spotify has no handles. Artist, album and track routes take a 22 character id or an open.spotify.com url. If you only have a name, search first.

GET /v1/spotify/search requires query. keyword and q are aliases. type is track, album, artist, playlist, show, episode or audiobook. Without type, every kind comes back, 10 of each. With type, you get 20 of that kind. type=show is how you find podcast ids. Episodes come back as songs with extra.type set to episode. Audiobooks come back as collections.

cursor pages. region is accepted and does not change the results. The reference says results follow the country of the server's IP.

The recorded search is a name, with no type, so the sample mixes kinds. The first items in that recording are tracks (a song: title, artists, album, duration_seconds, stats.plays). An artist hit is a profile. Read object on each item before you assume a shape.

curl -G "https://api.socialscrape.io/v1/spotify/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=taylor swift"

import os
import requests

params = {
    "query": "taylor swift",
}
res = requests.get(
    "https://api.socialscrape.io/v1/spotify/search",
    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},
    params=params,
)
body = res.json()

if body["ok"]:
    print(body["data"])
else:
    print(body["error"]["code"], body["error"]["message"])

const url = new URL("https://api.socialscrape.io/v1/spotify/search");
url.search = new URLSearchParams({
  "query": "taylor swift"
}).toString();
const res = await fetch(url, {
  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },
});
const body = await res.json();

if (body.ok) {
  console.log(body.data);
} else {
  console.error(body.error.code, body.error.message);
}

A track row's id is what you pass to the track endpoint. An artist row's id is what you pass to the artist endpoint.

The artist#

GET /v1/spotify/artist takes url or id. One of them. The description lists followers, monthly listeners, world rank, top cities, bio, links, top tracks, albums, singles, related artists and playlists. Most of that lives in extra, because it does not fit the shared profile.

The recorded request uses an artist id.

curl -G "https://api.socialscrape.io/v1/spotify/artist" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=06HL4z0CvFAxyc27GXpf02"

import os
import requests

params = {
    "id": "06HL4z0CvFAxyc27GXpf02",
}
res = requests.get(
    "https://api.socialscrape.io/v1/spotify/artist",
    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},
    params=params,
)
body = res.json()

if body["ok"]:
    print(body["data"])
else:
    print(body["error"]["code"], body["error"]["message"])

const url = new URL("https://api.socialscrape.io/v1/spotify/artist");
url.search = new URLSearchParams({
  "id": "06HL4z0CvFAxyc27GXpf02"
}).toString();
const res = await fetch(url, {
  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },
});
const body = await res.json();

if (body.ok) {
  console.log(body.data);
} else {
  console.error(body.error.code, body.error.message);
}

data.platform is spotify. name, bio, avatar_url, url, verified and external_url are the profile fields. stats.followers is the follower count. stats.following, stats.posts, stats.likes and stats.views are null when they do not apply. Monthly listeners are not stats.followers. They are extra.monthly_listeners, a number. extra.world_rank is the rank. extra.top_cities entries have city, country, region and listeners. extra.top_tracks entries have id, title, artists, url, duration_seconds, explicit and plays.

Also in extra on the recorded artist: albums, singles, compilations, appears_on, popular_releases, latest_release, related_artists, artist_playlists, discovered_on_playlists, featuring_playlists, uri, release_counts, concerts_count and playlists_count. Album entries include id, title, url, release_date and track_count. Use the album id with GET /v1/spotify/album when you need the track list (up to 200 tracks, plus label and copyright).

Sample. The recorded artist response is shortened. extra.monthly_listeners and extra.world_rank in that file are sample values from the recording. Do not publish them as a live chart.

Errors are invalid_params, unsupported_url and not_found.

A track#

GET /v1/spotify/track takes url or id. The description says title, artists, album, duration, lifetime play count and the 30 second preview URL. In the payload that is title, artists, album, duration_seconds, stats.plays and preview_url. isrc, explicit, cover_url and released_at are on the song too. extra includes uri, track_number, album_id and playable.

The recorded track request is an id. A successful call is 1 credit, same as the artist and the search page.

Cost and cache#

Search, artist, album and track are each 1 credit per successful request. They are cacheable for 30 days. max_age_days from 0 to 30 makes a cached repeat free. Failures are free. Signup is 100 credits, once, no card. See pricing and credits.

Limits#

You get public catalog metadata. You do not get a user's private playlists, their listening history, or a full audio file. preview_url is the preview Spotify publishes, and it can be null. region will not retarget the search to another country. Podcast episodes are songs with extra.type of episode, not a separate object, unless you asked for shows and then open the show.

Paging search spends one credit per page. Stop on has_more false. See pagination.

Rate limits are per team: 30 a minute on free credits. 429 is free and retryable. See rate limits.

The API is in early access. These routes are beta.

Next#

Artist: Spotify artist API, tutorial, reference. Search: Spotify search API and reference. Track: Spotify track API and reference. The hub is the Spotify API.

SoundCloud is a different catalog, with handles instead of 22 character ids: SoundCloud artists and tracks.