Docs menu

Spotify API endpoint

Spotify featured charts by country API

Returns Spotify country hub content. Defaults to the CHARTS content shelf for the requested country.

GETapiKey3 credits/requestSpotifyspotify.countryHubContentResponseDoc/spotify/featured-charts-by-country

Endpoint facts

Method: GET
API path: /spotify/featured-charts-by-country
Auth: apiKey
Credits: 3 credits/request
Charged on: Successful 2xx responses only
Platform: Spotify
Response schema: #/definitions/spotify.countryHubContentResponseDoc

Spotify scraping API Try Spotify featured charts by country API in Playground Spotify API documentation

How this endpoint behaves

Returns Spotify country-hub content. By default, it returns the CHARTS shelf used by https://open.spotify.com/popular-in/{country}.

Query parameters

country_code (optional): Two-letter Spotify popular-in country code. Defaults to us.
content_id (optional): Country hub content ID. Defaults to CHARTS. Supported values are CHARTS, POPULAR_ALBUMS, POPULAR_ARTISTS, and TRENDING_SONGS.

Notable response behavior

items contains the selected country hub content, such as featured chart playlists for CHARTS.
Playlist rows preserve Spotify attributes such as rank_type, last_updated, new_entries_count, and chart_entity_type when present.
The response includes supportedCountries and supportedContentIds enums for clients that need selectable filters.
When Spotify returns a partial response, meta.partialErrors records the number of tolerated upstream field errors. Because this endpoint requests a single shelf, an upstream error with no surviving items fails as 503 (the requested content is genuinely unavailable) — try a different content_id if one shelf is temporarily broken upstream.

Live monitoring

Monitored request: GET /spotify/featured-charts-by-country?content_id=POPULAR_ALBUMS&country_code=id
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 1.63 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /spotify/featured-charts-by-country?content_id=CHARTS&country_code=id
Items in items: 4
Fields filled in every checked item: 9

Field	Filled in, of 4 checked	Values in the sample
uri	4	“spotify:user:spotifycharts:playlist:37i9dQZEVXbIZK8aUquyx8” and 3 other values
type	4	Playlist in all 4
title	4	“Top Songs - Indonesia” and 3 other values
subtitle	4	Spotify in all 4
description	4	“Your weekly update of the most played tracks right now - In…” and 3 other values
imageUrl	4	charts-images.scdn.co
images	4	median 1 entry
attributes	4
owner	4

Request parameters

Parameter	Type	Required	Description	Example
country_code	string	No	Two-letter Spotify popular-in country code	id
content_id	string	No	Country hub content ID. Allowed: CHARTS, POPULAR_ALBUMS, POPULAR_ARTISTS, TRENDING_SONGS Allowed values: CHARTS, POPULAR_ALBUMS, POPULAR_ARTISTS, TRENDING_SONGS.	CHARTS
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/spotify/featured-charts-by-country?content_id=CHARTS" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "countryCode": "ID",
  "countryName": "Indonesia",
  "hexColor": "#F037A5",
  "contentId": "CHARTS",
  "title": "Featured Charts",
  "items": [
    {
      "uri": "spotify:playlist:37i9dQZEVXbObFQZ3JLcXt",
      "type": "Playlist",
      "title": "Top 50 - Indonesia",
      "subtitle": "Spotify",
      "description": "Your daily update of the most played tracks right now - Indonesia.",
      "externalUrl": "https://open.spotify.com/playlist/37i9dQZEVXbObFQZ3JLcXt",
      "attributes": {
        "rank_type": "plays",
        "chart_entity_type": "track"
      }
    }
  ],
  "meta": {
    "operationName": "countryHubContent",
    "itemCount": 1,
    "fetchedAt": "2026-05-13T20:03:43Z"
  }
}

Request schema

No body schema

Response schema

#/definitions/spotify.countryHubContentResponseDoc

Field	Type	Required	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.CountryHubContentResponse	No
data.contentId	string	No	CHARTS	Content identifier that was requested: `CHARTS`, `POPULAR_ALBUMS`, `POPULAR_ARTISTS` or `TRENDING_SONGS`.
data.countryCode	string	No	US	Country code the content was loaded for.
data.countryName	string	No	United States	Name of the country.
data.hexColor	string	No	#1DB954	Accent color of the country page, as a hex color code.
data.items	array	No		Items returned for the section.
data.items[].album	object	No		Album the item appears on.
data.items[].album.description	string	No	The official podcast of comedian Joe Rogan.	Description text of the result.
data.items[].album.externalUrl	string	No	https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk	Link to the result on open.spotify.com.
data.items[].album.imageUrl	string	No	https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b	URL of the main image for the result.
data.items[].album.images	array	No		Images available for the result, with their sizes.
data.items[].album.images[].height	integer	No	640	Image height in pixels.
data.items[].album.images[].url	string	No	https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0	URL of the image.
data.items[].album.images[].width	integer	No	640	Image width in pixels.
data.items[].album.publisher	string	No	Joe Rogan	Publisher or creator name of the result.
data.items[].album.subtitle	string	No	Joe Rogan	Secondary line shown under the title, such as the artist or creator name.
data.items[].album.title	string	No	The Joe Rogan Experience	Result title as Spotify shows it.
data.items[].album.type	string	No	Podcast	Kind of result as Spotify labels it, for example `Podcast`.
data.items[].album.uri	string	No	spotify:show:4rOoJ6Egrf8K2IrywzwOMk	Spotify URI of the result.
data.items[].artists	array	No		Artists credited on the item.
data.items[].artists[].description	string	No	The official podcast of comedian Joe Rogan.	Description text of the result.
data.items[].artists[].externalUrl	string	No	https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk	Link to the result on open.spotify.com.
data.items[].artists[].imageUrl	string	No	https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b	URL of the main image for the result.
data.items[].artists[].images	array	No		Images available for the result, with their sizes.
data.items[].artists[].images[].height	integer	No	640	Image height in pixels.
data.items[].artists[].images[].url	string	No	https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0	URL of the image.
data.items[].artists[].images[].width	integer	No	640	Image width in pixels.
data.items[].artists[].publisher	string	No	Joe Rogan	Publisher or creator name of the result.
data.items[].artists[].subtitle	string	No	Joe Rogan	Secondary line shown under the title, such as the artist or creator name.
data.items[].artists[].title	string	No	The Joe Rogan Experience	Result title as Spotify shows it.
data.items[].artists[].type	string	No	Podcast	Kind of result as Spotify labels it, for example `Podcast`.
data.items[].artists[].uri	string	No	spotify:show:4rOoJ6Egrf8K2IrywzwOMk	Spotify URI of the result.
data.items[].attributes	object	No	[object Object]	Additional key-value attributes Spotify returns for the item.
data.items[].description	string	No	Your daily update of the most played tracks right now.	Description text of the item.
data.items[].externalUrl	string	No	https://open.spotify.com/playlist/37i9dQZEVXbLRQDuF5jeBpM	Link to the item on open.spotify.com.
data.items[].imageUrl	string	No	https://charts-images.scdn.co/assets/locale_en/regional/daily/region_us_default.jpg	URL of the main image for the item.
data.items[].images	array	No		Images available for the item, with their sizes.
data.items[].images[].height	integer	No	640	Image height in pixels.
data.items[].images[].url	string	No	https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0	URL of the image.
data.items[].images[].width	integer	No	640	Image width in pixels.
data.items[].owner	object	No		User or account that owns the item.
data.items[].owner.description	string	No	The official podcast of comedian Joe Rogan.	Description text of the result.
data.items[].owner.externalUrl	string	No	https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk	Link to the result on open.spotify.com.
data.items[].owner.imageUrl	string	No	https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b	URL of the main image for the result.
data.items[].owner.images	array	No		Images available for the result, with their sizes.
data.items[].owner.images[].height	integer	No	640	Image height in pixels.
data.items[].owner.images[].url	string	No	https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0	URL of the image.
data.items[].owner.images[].width	integer	No	640	Image width in pixels.
data.items[].owner.publisher	string	No	Joe Rogan	Publisher or creator name of the result.
data.items[].owner.subtitle	string	No	Joe Rogan	Secondary line shown under the title, such as the artist or creator name.
data.items[].owner.title	string	No	The Joe Rogan Experience	Result title as Spotify shows it.
data.items[].owner.type	string	No	Podcast	Kind of result as Spotify labels it, for example `Podcast`.
data.items[].owner.uri	string	No	spotify:show:4rOoJ6Egrf8K2IrywzwOMk	Spotify URI of the result.
data.items[].subtitle	string	No	Spotify	Secondary line shown under the item title.
data.items[].title	string	No	Top 50 - USA	Item title as Spotify shows it.
data.items[].type	string	No	Playlist	Kind of item as Spotify labels it, for example `Playlist`.
data.items[].uri	string	No	spotify:playlist:37i9dQZEVXbLRQDuF5jeBpM	Spotify URI of the item.
data.meta	object	No		Details about this response.
data.meta.appVersion	string	No	1.2.90.403.gf901f20f	Version of the Spotify web player the data was read from.
data.meta.fetchedAt	string	No	2026-05-13T20:41:13Z	Time the data was fetched, in UTC (RFC 3339).
data.meta.itemCount	integer	No	20	Number of items returned.
data.meta.operationName	string	No	countryHubContent	Name of the Spotify web player operation that returned the data.
data.meta.partialErrors	integer	No	1	PartialErrors counts upstream GraphQL field errors tolerated alongside usable items. Zero on a fully clean response.
data.supportedContentIds	array	No		Content sections available on the country page.
data.supportedContentIds[].id	string	No	CHARTS	Content identifier to pass when requesting that section, for example `CHARTS`.
data.supportedContentIds[].title	string	No	Featured Charts	Section heading as Spotify shows it.
data.supportedCountries	array	No		Countries Spotify offers a popular-in page for.
data.supportedCountries[].code	string	No	us
data.supportedCountries[].name	string	No	United States	Country name in English.
data.title	string	No	Featured Charts	Section heading as Spotify shows it.
msg	unknown	No		Msg is the message that describes the result of the request @example "Request successful"

Failure responses

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

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/spotify/featured-charts-by-country?content_id=CHARTS" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More Spotify endpoint docs Spotify scraping API Spotify album API documentation Spotify album tracks API documentation Spotify Albums Search API documentation Spotify artist API documentation Spotify artist albums API documentation Spotify artist playlists API documentation

Open in Playground Back to group

Endpoint facts

Method

GET

API path

/spotify/featured-charts-by-country

Auth

apiKey

Credits

3 credits/request

Charged on

Successful 2xx responses only

Platform

Spotify

Response schema

#/definitions/spotify.countryHubContentResponseDoc

How this endpoint behaves

Returns Spotify country-hub content. By default, it returns the CHARTS shelf used by https://open.spotify.com/popular-in/{country}.

Query parameters

country_code (optional): Two-letter Spotify popular-in country code. Defaults to us.

content_id (optional): Country hub content ID. Defaults to CHARTS. Supported values are CHARTS, POPULAR_ALBUMS, POPULAR_ARTISTS, and TRENDING_SONGS.

Notable response behavior

items contains the selected country hub content, such as featured chart playlists for CHARTS.

Playlist rows preserve Spotify attributes such as rank_type, last_updated, new_entries_count, and chart_entity_type when present.

The response includes supportedCountries and supportedContentIds enums for clients that need selectable filters.

When Spotify returns a partial response, meta.partialErrors records the number of tolerated upstream field errors. Because this endpoint requests a single shelf, an upstream error with no surviving items fails as 503 (the requested content is genuinely unavailable) — try a different content_id if one shelf is temporarily broken upstream.

Sampled response

Request, 14 Oct 2026

GET /spotify/featured-charts-by-country?content_id=CHARTS&country_code=id

Items in items

Fields filled in every checked item

Field	Filled in, of 4 checked	Values in the sample
uri	4	“spotify:user:spotifycharts:playlist:37i9dQZEVXbIZK8aUquyx8” and 3 other values
type	4	Playlist in all 4
title	4	“Top Songs - Indonesia” and 3 other values
subtitle	4	Spotify in all 4
description	4	“Your weekly update of the most played tracks right now - In…” and 3 other values
imageUrl	4	charts-images.scdn.co
images	4	median 1 entry
attributes	4
owner	4

Request parameters

Parameter	Type	Required	Description	Example
country_code	string	No	Two-letter Spotify popular-in country code	id
content_id	string	No	Country hub content ID. Allowed: CHARTS, POPULAR_ALBUMS, POPULAR_ARTISTS, TRENDING_SONGS Allowed values: CHARTS, POPULAR_ALBUMS, POPULAR_ARTISTS, TRENDING_SONGS.	CHARTS
x-api-key (header)	string	Yes	API key required

{ "countryCode": "ID", "countryName": "Indonesia", "hexColor": "#F037A5", "contentId": "CHARTS", "title": "Featured Charts", "items": [ { "uri": "spotify:playlist:37i9dQZEVXbObFQZ3JLcXt", "type": "Playlist", "title": "Top 50 - Indonesia", "subtitle": "Spotify", "description": "Your daily update of the most played tracks right now - Indonesia.", "externalUrl": "https://open.spotify.com/playlist/37i9dQZEVXbObFQZ3JLcXt", "attributes": { "rank_type": "plays", "chart_entity_type": "track" } } ], "meta": { "operationName": "countryHubContent", "itemCount": 1, "fetchedAt": "2026-05-13T20:03:43Z" } }

Field

Type

Required

Enum

Bounds

Example

Description

code

integer

Code is the HTTP status code or a custom code used to indicate the result of the request @example 200

data

spotify.CountryHubContentResponse

data.contentId

string

CHARTS

Content identifier that was requested: `CHARTS`, `POPULAR_ALBUMS`, `POPULAR_ARTISTS` or `TRENDING_SONGS`.

data.countryCode

string

Country code the content was loaded for.

data.countryName

string

United States

Name of the country.

data.hexColor

string

#1DB954

Accent color of the country page, as a hex color code.

data.items

array

Items returned for the section.

data.items[].album

object

Album the item appears on.

data.items[].album.description

string

The official podcast of comedian Joe Rogan.

Description text of the result.

data.items[].album.externalUrl

string

https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk

Link to the result on open.spotify.com.

data.items[].album.imageUrl

string

https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b

URL of the main image for the result.

data.items[].album.images

array

Images available for the result, with their sizes.

data.items[].album.images[].height

integer

640

Image height in pixels.

data.items[].album.images[].url

string

https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0

URL of the image.

data.items[].album.images[].width

integer

640

Image width in pixels.

data.items[].album.publisher

string

Joe Rogan

Publisher or creator name of the result.

data.items[].album.subtitle

string

Joe Rogan

Secondary line shown under the title, such as the artist or creator name.

data.items[].album.title

string

The Joe Rogan Experience

Result title as Spotify shows it.

data.items[].album.type

string

Podcast

Kind of result as Spotify labels it, for example `Podcast`.

data.items[].album.uri

string

spotify:show:4rOoJ6Egrf8K2IrywzwOMk

Spotify URI of the result.

data.items[].artists

array

Artists credited on the item.

data.items[].artists[].description

string

The official podcast of comedian Joe Rogan.

Description text of the result.

data.items[].artists[].externalUrl

string

https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk

Link to the result on open.spotify.com.

data.items[].artists[].imageUrl

string

https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b

URL of the main image for the result.

data.items[].artists[].images

array

Images available for the result, with their sizes.

data.items[].artists[].images[].height

integer

640

Image height in pixels.

data.items[].artists[].images[].url

string

https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0

URL of the image.

data.items[].artists[].images[].width

integer

640

Image width in pixels.

data.items[].artists[].publisher

string

Joe Rogan

Publisher or creator name of the result.

data.items[].artists[].subtitle

string

Joe Rogan

Secondary line shown under the title, such as the artist or creator name.

data.items[].artists[].title

string

The Joe Rogan Experience

Result title as Spotify shows it.

data.items[].artists[].type

string

Podcast

Kind of result as Spotify labels it, for example `Podcast`.

data.items[].artists[].uri

string

spotify:show:4rOoJ6Egrf8K2IrywzwOMk

Spotify URI of the result.

data.items[].attributes

object

[object Object]

Additional key-value attributes Spotify returns for the item.

data.items[].description

string

Your daily update of the most played tracks right now.

Description text of the item.

data.items[].externalUrl

string

https://open.spotify.com/playlist/37i9dQZEVXbLRQDuF5jeBpM

Link to the item on open.spotify.com.

data.items[].imageUrl

string

https://charts-images.scdn.co/assets/locale_en/regional/daily/region_us_default.jpg

URL of the main image for the item.

data.items[].images

array

Images available for the item, with their sizes.

data.items[].images[].height

integer

640

Image height in pixels.

data.items[].images[].url

string

https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0

URL of the image.

data.items[].images[].width

integer

640

Image width in pixels.

data.items[].owner

object

User or account that owns the item.

data.items[].owner.description

string

The official podcast of comedian Joe Rogan.

Description text of the result.

data.items[].owner.externalUrl

string

https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk

Link to the result on open.spotify.com.

data.items[].owner.imageUrl

string

https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b

URL of the main image for the result.

data.items[].owner.images

array

Images available for the result, with their sizes.

data.items[].owner.images[].height

integer

640

Image height in pixels.

data.items[].owner.images[].url

string

https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0

URL of the image.

data.items[].owner.images[].width

integer

640

Image width in pixels.

data.items[].owner.publisher

string

Joe Rogan

Publisher or creator name of the result.

data.items[].owner.subtitle

string

Joe Rogan

Secondary line shown under the title, such as the artist or creator name.

data.items[].owner.title

string

The Joe Rogan Experience

Result title as Spotify shows it.

data.items[].owner.type

string

Podcast

Kind of result as Spotify labels it, for example `Podcast`.

data.items[].owner.uri

string

spotify:show:4rOoJ6Egrf8K2IrywzwOMk

Spotify URI of the result.

data.items[].subtitle

string

Spotify

Secondary line shown under the item title.

data.items[].title

string

Top 50 - USA

Item title as Spotify shows it.

data.items[].type

string

Playlist

Kind of item as Spotify labels it, for example `Playlist`.

data.items[].uri

string

spotify:playlist:37i9dQZEVXbLRQDuF5jeBpM

Spotify URI of the item.

data.meta

object

Details about this response.

data.meta.appVersion

string

1.2.90.403.gf901f20f

Version of the Spotify web player the data was read from.

data.meta.fetchedAt

string

2026-05-13T20:41:13Z

Time the data was fetched, in UTC (RFC 3339).

data.meta.itemCount

integer

Number of items returned.

data.meta.operationName

string

countryHubContent

Name of the Spotify web player operation that returned the data.

data.meta.partialErrors

integer

PartialErrors counts upstream GraphQL field errors tolerated alongside usable items. Zero on a fully clean response.

data.supportedContentIds

array

Content sections available on the country page.

data.supportedContentIds[].id

string

CHARTS

Content identifier to pass when requesting that section, for example `CHARTS`.

data.supportedContentIds[].title

string

Featured Charts

Section heading as Spotify shows it.

data.supportedCountries

array

Countries Spotify offers a popular-in page for.

data.supportedCountries[].code

string

data.supportedCountries[].name

string

United States

Country name in English.

data.title

string

Featured Charts

Section heading as Spotify shows it.

msg

unknown

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

Spotify featured charts by country API

Endpoint facts

How this endpoint behaves

Query parameters

Notable response behavior

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

Spotify featured charts by country API

Endpoint facts

How this endpoint behaves

Query parameters

Notable response behavior

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related