SpotifyPodcasts API endpoint
Returns Spotify podcast chart rankings from podcastcharts.byspotify.com. The chart and region parameters are validated against Spotify's supported podcast chart slugs and countries. Category charts are available only in au, br, de, gb, mx, se, and us.
/spotify-podcasts/chartsMCP tool: spotify_podcasts_charts
Returns Spotify podcast chart rankings.
Path/query/body parameters:
chart query string, optional. Defaults to top-podcasts. Supported values are top-podcasts, top-episodes, trending, arts, business, comedy, education, fiction, health-fitness, history, leisure, music, news, religion-spirituality, science, society-culture, sports, technology, true-crime, and tv-film.region query string, optional. Defaults to us. Supported values are ar, au, at, br, ca, cl, co, dk, fi, fr, de, in, id, ie, it, jp, mx, nz, no, ph, pl, es, se, nl, gb, and us.limit query integer, optional. Defaults to 100 and is clamped to 1-100.Notable response behavior:
chart or region values return 400.top-podcasts, top-episodes, and trending support all listed regions. Category charts support au, br, de, gb, mx, se, and us.top-episodes items include episode fields plus the parent show fields when Spotify returns them.503.items[].rank is assigned from the upstream array order.| Field | Filled in, of 50 checked | Values in the sample |
|---|---|---|
| rank | 50 | 1 to 50, median 25 |
| uri | 50 | “spotify:show:353ryGdZNlebaiqkCcy3Yc” and 49 other values |
| rankMove | 50 | UNCHANGED (32), UP (10), DOWN (8) |
| name | 50 | “Live Free with Josh Howerton” and 49 other values |
| publisher | 50 | “Lakepointe Church” and 44 other values |
| imageUrl | 50 | i.scdn.co |
| description | 50 | median 368 characters |
| externalUrl | 50 | open.spotify.com |
| showUri | 50 | “spotify:show:353ryGdZNlebaiqkCcy3Yc” and 49 other values |
| showName | 50 | “Live Free with Josh Howerton” and 49 other values |
| showPublisher | 50 | “Lakepointe Church” and 44 other values |
| showImageUrl | 50 | i.scdn.co |
| showDescription | 50 | median 368 characters |
| showExternalUrl | 50 | open.spotify.com |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| chart | string | No | Chart slug. Allowed: top-podcasts, top-episodes, trending, arts, business, comedy, education, fiction, health-fitness, history, leisure, music, news, religion-spirituality, science, society-culture, sports, technology, true-crime, tv-film Allowed values: top-podcasts, top-episodes, trending, arts, business, comedy, education, fiction, health-fitness, history, leisure, music, news, religion-spirituality, science, society-culture, sports, technology, true-crime, tv-film. | religion-spirituality | |
| region | string | No | Two-letter region code. Allowed: ar, au, at, br, ca, cl, co, dk, fi, fr, de, in, id, ie, it, jp, mx, nz, no, ph, pl, es, se, nl, gb, us Allowed values: ar, au, at, br, ca, cl, co, dk, fi, fr, de, in, id, ie, it, jp, mx, nz, no, ph, pl, es, se, nl, gb, us. | us | |
| limit | integer | No | Result limit, clamped to 1-100 | 100 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/spotify-podcasts/charts?chart=top-podcasts®ion=ar&limit=10" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"chart": "religion-spirituality",
"chartName": "Religion & Spirituality",
"chartType": "category",
"region": "us",
"regionName": "United States",
"limit": 100,
"items": [
{
"rank": 1,
"uri": "spotify:show:4Pppt42NPK2XzKwNIoW7BR",
"rankMove": "UNCHANGED",
"name": "The Bible in a Year (with Fr. Mike Schmitz)",
"publisher": "Ascension",
"imageUrl": "https://i.scdn.co/image/example",
"description": "A podcast description.",
"externalUrl": "https://open.spotify.com/show/4Pppt42NPK2XzKwNIoW7BR"
}
],
"meta": {
"sourceUrl": "https://podcastcharts.byspotify.com/api/charts/religion-spirituality?limit=100®ion=us",
"count": 1,
"fetchedAt": "2026-05-13T15:22:41Z"
}
}
}Request schema
No body schema
Response schema
#/definitions/spotify.chartsResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | Code is the HTTP status code or a custom code used to indicate the result of the request @example 200 | |||
| data | spotify.ChartResponse | No | ||||
| data.chart | string | No | top-podcasts | Chart identifier that was requested, for example `top-podcasts`. | ||
| data.chartName | string | No | Top Podcasts | Display name of the chart. | ||
| data.chartType | string | No | chart | Whether the chart is an overall `chart` or a `category` chart. | ||
| data.items | array | No | Chart entries, ordered by rank. | |||
| data.items[].description | string | No | The official podcast of comedian Joe Rogan. | Description text of the chart entry. | ||
| data.items[].episodeDescription | string | No | A representative chart episode. | Description text of the episode, for episode charts. | ||
| data.items[].episodeExternalUrl | string | No | https://open.spotify.com/episode/2C2Y5kNq7qCVOVhbA0G3os | Link to the episode on open.spotify.com, for episode charts. | ||
| data.items[].episodeImageUrl | string | No | https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b | URL of the episode's cover image, for episode charts. | ||
| data.items[].episodeName | string | No | Example episode | Episode title as Spotify shows it, for episode charts. | ||
| data.items[].episodeUri | string | No | spotify:episode:2C2Y5kNq7qCVOVhbA0G3os | Spotify URI of the episode, for episode charts. | ||
| data.items[].externalUrl | string | No | https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk | Link to the chart entry on open.spotify.com. | ||
| data.items[].imageUrl | string | No | https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b | URL of the cover image for the chart entry. | ||
| data.items[].name | string | No | The Joe Rogan Experience | Title of the chart entry (episode title for episode charts, otherwise show title). | ||
| data.items[].publisher | string | No | Joe Rogan | Name of the publisher of the show. | ||
| data.items[].rank | integer | No | 1 | Position of the entry in the chart, starting at 1. | ||
| data.items[].rankMove | string | No | UNCHANGED | Change in rank since the previous chart period, as Spotify labels it, for example `UNCHANGED`. | ||
| data.items[].showDescription | string | No | The official podcast of comedian Joe Rogan. | Description text of the show. | ||
| data.items[].showExternalUrl | string | No | https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk | Link to the show on open.spotify.com. | ||
| data.items[].showImageUrl | string | No | https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b | URL of the show's cover image. | ||
| data.items[].showName | string | No | The Joe Rogan Experience | Show title as Spotify shows it. | ||
| data.items[].showPublisher | string | No | Joe Rogan | Name of the show's publisher. | ||
| data.items[].showUri | string | No | spotify:show:4rOoJ6Egrf8K2IrywzwOMk | Spotify URI of the show. | ||
| data.items[].uri | string | No | spotify:show:4rOoJ6Egrf8K2IrywzwOMk | Spotify URI of the chart entry (an episode for episode charts, otherwise a show). | ||
| data.limit | integer | No | 100 | Maximum number of chart entries requested. | ||
| data.meta | object | No | Details about this response. | |||
| data.meta.count | integer | No | 100 | Number of chart entries returned. | ||
| data.meta.fetchedAt | string | No | 2026-05-13T20:41:13Z | Time the data was fetched, in UTC (RFC 3339). | ||
| data.meta.sourceUrl | string | No | https://podcastcharts.byspotify.com/api/charts/top-podcasts?region=us | URL the data was read from. | ||
| data.region | string | No | us | Region code the chart was loaded for. | ||
| data.regionName | string | No | United States | Name of the chart region. | ||
| msg | unknown | No | Msg is the message that describes the result of the request @example "Request successful" |
| Status | Description | Schema |
|---|---|---|
| 400 | Missing or invalid parameters | #/definitions/app.Response |
| 429 | Rate limit exceeded | #/definitions/app.Response |
| 503 | Spotify upstream request failed | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/spotify-podcasts/charts?chart=top-podcasts®ion=ar&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"