Guide
Spotify charts API: Top 200 and viral rankings as JSON
Spotify publishes its charts on charts.spotify.com as a web app. The Web API has no chart resource at all, so every chart dashboard on GitHub scrapes that page. These 6 endpoints return the same rankings as JSON, with stream counts, rank movement and the metadata attached.
By Eduardo Airaudo, maintainer of the API · Updated 3 September 2026
Why scraping charts.spotify.com keeps breaking
The Web API's resources are catalogue and user data — albums, artists, tracks, playlists, shows, a user's library. There is no chart resource, no ranking field on a track, and no scope that adds one. What exists is the charts site, which renders in the browser and gates its bulk downloads behind a login.
So the usual approach is a headless browser and a set of CSS selectors, re-fixed every time the page markup moves, plus session handling to get past the login. That is a scraper to maintain, not a data source.
These endpoints do that work upstream and answer with JSON. A daily job is one request per chart and per country; a backfill is the same request with a date.
The 6 chart endpoints
- Top 20 by monthly listenersNo parameters/top_20_by_monthly_listeners
- Top 200 tracksperiod, country, date — optional/top_200_tracks
- Top artists chartperiod, country — optional/top_artists
- Top albums chartperiod, country — optional/top_albums
- Viral tracks chartcountry — optional/viral_tracks
- Top 20 by followersNo parameters/top_20_by_followers
Every one of them is runnable from the Charts group page, or against live data on the charts demo.
What one chart row contains
Read off the recorded /top_200_tracks response, captured 2025-06-07: 200 rows, each split into the ranking and the track it points at.
chartEntryData
- currentRank
- Position on this chart, 1 to 200.
- previousRank
- Position on the previous chart, or -1 when the track was not on it — which is how you compute movement without storing yesterday's file.
- peakRank / peakDate
- The best position the track has reached and the day it did, so a chart run can be summarised from a single response.
- appearancesOnChart
- Total charts the track has appeared on, alongside consecutiveAppearancesOnChart for the current run.
- rankingMetric
- The number the ranking is made of: { value, type }. In the recording the type is STREAMS and the value is a stream count as a string.
- entryStatus / entryRank / entryDate
- How the row got here — NEW_ENTRY in the recording — with the rank and date it first entered.
trackMetadata
- trackName / trackUri
- The title and the spotify:track: URI, which is the id every other endpoint on this site takes.
- displayImageUri
- Cover art, ready to render — no second request to an album endpoint.
- artists[]
- Each with name and spotifyUri, so an artist page can be linked straight from a chart row.
- labels[] / producers[] / songWriters[]
- Credits as the chart carries them. Populated unevenly upstream: the recording has a label and empty producer and writer arrays.
- releaseDate
- Release day of the charting track, for filtering new music out of a catalogue chart.
Pull today's Top 200
| curl -X GET \ |
| "https://spotify-proxy.checkleaked.cc/top_200_tracks?period=daily&country=global" \ |
| -H "x-api-key: $SPOTIFY_API_KEY" |
Drop date for the latest chart, or set it to any published day to backfill. country defaults to global and period to daily.
What people build with it
- Daily ingestion into a warehouse: one request per country per chart, keyed on currentRank and entryDate.
- Movement alerts — previousRank and currentRank in the same row make a threshold check a comparison, not a join against yesterday's snapshot.
- A&R and label dashboards: entryStatus NEW_ENTRY plus releaseDate isolates debut entries from catalogue tracks.
- Playlist tooling that seeds from what is actually charting in a market rather than from a global list.
- Backfills and research, via the date parameter on the Top 200 tracks endpoint.
Questions
Does the Spotify Web API have a charts endpoint?
No. The Web API's resources cover the catalogue and user data; no path returns a chart and no scope adds one. Spotify publishes charts through charts.spotify.com instead, which is a web app rather than a documented API.
Which charts are covered?
Top 200 tracks, viral tracks, top artists and top albums by period and country, plus the top 20 artists by followers and by monthly listeners. Six endpoints in the Charts group.
Can I get historical charts?
GET /top_200_tracks takes a date parameter, so a past chart is the same request with a different day. The other chart endpoints return the current ranking.
Is stream count included?
Yes, as rankingMetric: an object with a value and a type. In the recorded response the type is STREAMS and the value is the stream count for that chart period.
How do I compute rank movement?
Each row carries previousRank next to currentRank, and -1 where the track was not on the previous chart. No second request and no stored snapshot are needed.
Which countries can I ask for?
The country parameter takes a market code and defaults to global. GET /markets returns the countries Spotify is available in.
How often should I poll?
Once per chart per country per day is enough — the underlying charts are published daily and weekly, and period selects which. Polling faster returns the same rows.
Sources
- Spotify Web API reference — the full resource list — no chart resource appears in it.
- Spotify Charts — where Spotify publishes the rankings these endpoints return.
- GET /top_200_tracks on this site — the recorded 200-row response this page describes, with its capture date.
Get a key and pull today's chart
Same endpoints on all three, priced differently. RapidAPI's free tier is 1,000 requests a month — enough for a daily job on a handful of countries.