Spotify APIspotify.com ↗
Search Spotify's catalog and retrieve artist bios, top tracks, follower counts, discographies, top cities, and upcoming releases via 4 JSON endpoints.
What is the Spotify API?
This API exposes 4 endpoints covering Spotify's music catalog: search across tracks, albums, artists, playlists, and podcasts; retrieve deep artist profiles including biography, follower count, monthly listeners, world ranking, and top listener cities; and fetch upcoming or recent releases by artist or record label. The get_artist endpoint alone returns over 10 distinct fields, including verified status, top tracks with play counts, and related artists.
curl -X POST 'https://api.parse.bot/scraper/143b411a-341f-40ea-90ca-b73c6cdbb436/search' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"type": "all",
"limit": "5",
"query": "Adele",
"offset": "0"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace spotify-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Spotify Music Library SDK — search catalog, explore artists, discover releases."""
from parse_apis.Spotify_Music_Library_API import Spotify, ContentType, ArtistNotFound
client = Spotify()
# Search for tracks by a popular artist, capped at 3 results.
for track in client.catalogs.search(query="Adele", type=ContentType.TRACKS, limit=3):
print(track.name, track.artists, track.duration_ms)
# Get an artist summary from search, then fetch full details.
artist_summary = client.catalogs.search(query="Taylor Swift", type=ContentType.ARTISTS, limit=1).first()
if artist_summary:
full_artist = artist_summary.details()
print(full_artist.name, full_artist.monthly_listeners, full_artist.followers)
# Browse the artist's releases (upcoming + recent).
for release in full_artist.releases(limit=3):
print(release.name, release.artists, release.release_date, release.is_upcoming)
# Discover upcoming/recent releases for a record label.
for release in client.releases.upcoming(label_or_distributor="STMPD RCRDS", limit=3):
print(release.name, release.artists, release.release_date, release.is_upcoming)
# Typed error handling: attempt to get a non-existent artist.
try:
client.artists.get(artist_id="does_not_exist_xyz", limit=1).first()
except ArtistNotFound as exc:
print(f"Artist not found: {exc.artist_id}")
print("exercised: catalogs.search / artist_summary.details / artist.releases / releases.upcoming / artists.get / error handling")
Full-text search across Spotify's music catalog. Returns tracks, artists, albums, playlists, and podcasts matching the query. Results can be filtered by content type and paginated via offset. Each result category returns up to `limit` items per request.
| Param | Type | Description |
|---|---|---|
| type | string | Filter results to a specific content type. Omitted or 'all' returns all types. |
| limit | integer | Maximum number of results per content type (1-50). |
| queryrequired | string | Search query string (artist name, track title, album, etc.). |
| offset | integer | Offset for pagination within each content type. |
{
"type": "object",
"fields": {
"query": "string",
"albums": "array of album objects with id, name, artists, year, type, image_url, uri",
"tracks": "array of track objects with id, name, artists, album_name, duration_ms, image_url, uri",
"artists": "array of artist objects with id, name, image_url, uri",
"podcasts": "array of podcast objects with id, name, publisher, description, image_url, uri",
"playlists": "array of playlist objects with id, name, description, owner, image_url, uri",
"type_filter": "string"
},
"sample": {
"data": {
"query": "Taylor Swift",
"albums": [
{
"id": "4a6NzYL1YHRUgx9e3YZI6I",
"uri": "spotify:album:4a6NzYL1YHRUgx9e3YZI6I",
"name": "The Life of a Showgirl",
"type": "ALBUM",
"year": 2025,
"artists": [
"Taylor Swift"
],
"image_url": "https://i.scdn.co/image/ab67616d00001e02d7812467811a7da6e6a44902"
}
],
"tracks": [
{
"id": "53iuhJlwXhSER5J2IYYv1W",
"uri": "spotify:track:53iuhJlwXhSER5J2IYYv1W",
"name": "The Fate of Ophelia",
"artists": [
"Taylor Swift"
],
"image_url": "https://i.scdn.co/image/ab67616d00001e02d7812467811a7da6e6a44902",
"album_name": "The Life of a Showgirl",
"duration_ms": 226073
}
],
"artists": [
{
"id": "06HL4z0CvFAxyc27GXpf02",
"uri": "spotify:artist:06HL4z0CvFAxyc27GXpf02",
"name": "Taylor Swift",
"image_url": "https://i.scdn.co/image/ab6761610000e5ebe2e8e7ff002a4afda1c7147e"
}
],
"podcasts": [
{
"id": "57chMWWvJOZlwLEPZyxXKg",
"uri": "spotify:show:57chMWWvJOZlwLEPZyxXKg",
"name": "13: A Taylor Swift Fan Podcast",
"image_url": "https://i.scdn.co/image/ab6765630000f68d03e8bd9c6e7656b14efd2602",
"publisher": "Jane Doe",
"description": null
}
],
"playlists": [
{
"id": "0Y44bc2Fd2IfbhqSPnNlTC",
"uri": "spotify:playlist:0Y44bc2Fd2IfbhqSPnNlTC",
"name": "Taylor Swift: Hits and Best of",
"owner": "John Doe",
"image_url": "https://mosaic.scdn.co/640/ab67616d00001e025076e4160d018e378f488c33",
"description": "greatest songs"
}
],
"type_filter": "all"
},
"status": "success"
}
}About the Spotify API
Search and Discovery
The search endpoint accepts a query string and an optional type filter to narrow results to tracks, albums, artists, playlists, or podcasts. Without a type filter, all five content categories are returned simultaneously, each paginated independently via offset and limit (1–50 items per type per request). Every result object carries a uri suitable for direct linking into Spotify clients, plus an image_url for cover art or artist photos.
Artist Profiles
The get_artist endpoint takes a 22-character Spotify artist_id — available from search results — and returns a full artist record: biography, followers, verified boolean, image_url, a list of albums and singles each with year and total_tracks, and a top_cities array showing the cities and countries where the artist has the most listeners. This makes it practical to build audience-geography tools or artist research dashboards without additional lookups.
Release Tracking
Two endpoints handle release monitoring. get_artist_releases returns an artist's discography sorted newest-first, with each entry tagged is_upcoming: true when the release date is in the future. The only_upcoming boolean filters out past releases entirely. get_upcoming_releases works at the label level: supply a label_or_distributor name (e.g. 'Interscope Records') and it aggregates upcoming and recent releases across all associated artists, returning the same is_upcoming-tagged release objects with artist attribution.
The Spotify API is a managed, monitored endpoint for spotify.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when spotify.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official spotify.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track upcoming album and single release dates for a specific artist using
get_artist_releaseswithonly_upcoming: true. - Monitor all scheduled releases from a record label or distributor using
get_upcoming_releaseswith the label name. - Display an artist's top listener cities with
top_citiesfromget_artistto support tour routing or audience analysis. - Build a catalog search interface covering tracks, albums, playlists, and podcasts from a single
searchquery. - Populate artist profile cards with
biography,followers,verifiedstatus, and cover art fromget_artist. - Identify an artist's full discography split into
albumsandsinglesarrays, each with release year and track count. - Cross-reference artist popularity by comparing
followersand monthly listener data across multiple artist IDs.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Spotify have an official developer API?+
What does `get_artist` return beyond basic profile info?+
name, image_url, and biography, it returns followers, verified status, an albums array and a singles array (each with id, name, year, total_tracks, and uri), and a top_cities array of city-level listener geography objects containing city, country, and listeners.Does the search endpoint return play counts or popularity scores?+
get_artist top tracks. You can fork this API on Parse and revise it to surface popularity or play-count fields in search results if that data is present in the source.Can I retrieve podcast episode-level data, not just podcast objects?+
search endpoint returns podcast objects with id, name, publisher, description, and image_url, but individual episode listings are not exposed by any endpoint. You can fork this API on Parse and revise it to add an episode-detail endpoint.How do I paginate through a large set of search results?+
offset and limit parameters on search. limit controls how many items are returned per content type (max 50), and offset shifts the starting position within each type's result set. Increment offset by limit on each call to page through deeper results.