Retrieve Spotify popular by country

Returns normalized Spotify country hub shelves from Spotify's countryHubsPage Pathfinder response. The country_code parameter accepts Spotify popular-in country codes from open.spotify.com/popular-in/us.

GETapiKey3 credits/requestSpotifyspotify.countryHubResponseDoc/spotify/popular-by-country

Overview

View Spotify platform page Open in Playground Copy language examples

Request schema

Name	In	Type	Required	Enum	Example	Description
country_code	query	string	No		us	Two-letter Spotify popular-in country code
x-api-key	header	string	Yes			API key required

Authentication

Send your scraping API key in the x-api-key header. Use the console API Keys page to rotate or select the active key.

Billing

Endpoint usage is metered in credits. The plan prices, included credits, limits, and overage rates below match the active backend billing configuration.

Credit cost: 3 credits/request
Charged response: Successful 2xx responses

Plan	Price	Included credits	Daily cap	Rate limit	Overage
Free	$0/mo	2,000	500 daily credits	5/min	No overage
Starter	$9/mo	20,000	5,000 daily credits	15/min	$0.75/1,000 overage credits when enabled
Growth	$29/mo	100,000	25,000 daily credits	45/min	$0.45/1,000 overage credits when enabled
Pro	$79/mo	400,000	No daily cap	120/min	$0.30/1,000 overage credits
Business	$199/mo	1,200,000	No daily cap	300/min	$0.20/1,000 overage credits
Enterprise	$499/mo	5,000,000	No daily cap	1,000/min	$0.12/1,000 overage credits

Infrastructure behavior

This endpoint is executed through Crawlora's managed scraping infrastructure.

Proxy strategy: managed automatically where needed
Browser rendering: enabled for supported targets that require rendered HTML or JavaScript execution
Browser cluster: supported dynamic workloads can be routed through distributed browser instances
Retry behavior: automatic retry/fallback may be used depending on endpoint type
Challenge handling: challenged pages or unusable upstream HTML are detected and surfaced clearly when they cannot be used
Billing: credits are charged only for successful 2xx responses
Observability: responses include request context where available

Response behavior

- `sections` contains country-hub shelves such as `CHARTS`, `POPULAR_ALBUMS`, `POPULAR_ARTISTS`, and `TRENDING_SONGS`. - Playlist chart rows preserve Spotify attributes such as `rank_type` and `last_updated` when present. - Track and album rows include normalized artist and album summaries when Spotify returns them.

Error behavior

Crawlora does not silently return bad data when the upstream page cannot be used.

Status	Common failure case
400	Invalid input or missing required parameter
429	Plan or endpoint rate limit exceeded
500	Internal execution error
502	Upstream platform failed, returned unusable HTML, or served a challenge page that could not be resolved

When possible, Crawlora returns structured error context so your integration can retry, back off, or inspect the request.

Failure responses

Status	Description	Schema
400	Missing or invalid parameters	#/definitions/app.Response
429	Rate limit exceeded	#/definitions/app.Response
502	Spotify upstream request failed	#/definitions/app.Response

Example response

{
  "countryCode": "US",
  "countryName": "United States",
  "hexColor": "#EB1E32",
  "sections": [
    {
      "contentId": "CHARTS",
      "title": "Charts",
      "totalCount": 1,
      "items": [
        {
          "uri": "spotify:playlist:37i9dQZEVXbLRQDuF5jeBp",
          "type": "Playlist",
          "title": "Top 50 - USA",
          "subtitle": "Spotify",
          "description": "Your daily update of the most played tracks right now - USA.",
          "externalUrl": "https://open.spotify.com/playlist/37i9dQZEVXbLRQDuF5jeBp"
        }
      ]
    }
  ],
  "supportedCountries": [
    {
      "code": "us",
      "name": "United States"
    }
  ],
  "meta": {
    "operationName": "countryHubsPage",
    "sectionCount": 1,
    "itemCount": 1,
    "fetchedAt": "2026-05-13T19:45:00Z"
  }
}

Request schema

No body schema

Response schema

#/definitions/spotify.countryHubResponseDoc

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.CountryHubResponse	No
data.countryCode	string	No	US
data.countryName	string	No	United States
data.hexColor	string	No	#1DB954
data.meta	spotify.CountryHubMeta	No
data.meta.appVersion	string	No	1.2.90.403.gf901f20f
data.meta.fetchedAt	string	No	2026-05-13T20:41:13Z
data.meta.itemCount	integer	No	20
data.meta.operationName	string	No	countryHubsPage
data.meta.sectionCount	integer	No	5
data.sections	array	No
data.sections[].contentId	string	No	CHARTS
data.sections[].items	array	No
data.sections[].items[].album	spotify.SearchResultSummary	No
data.sections[].items[].album.description	string	No	The official podcast of comedian Joe Rogan.
data.sections[].items[].album.externalUrl	string	No	https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk
data.sections[].items[].album.imageUrl	string	No	https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b
data.sections[].items[].album.images	array	No
data.sections[].items[].album.images[].height	integer	No	640
data.sections[].items[].album.images[].url	string	No	https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0
data.sections[].items[].album.images[].width	integer	No	640
data.sections[].items[].album.publisher	string	No	Joe Rogan
data.sections[].items[].album.subtitle	string	No	Joe Rogan
data.sections[].items[].album.title	string	No	The Joe Rogan Experience
data.sections[].items[].album.type	string	No	Podcast
data.sections[].items[].album.uri	string	No	spotify:show:4rOoJ6Egrf8K2IrywzwOMk
data.sections[].items[].artists	array	No
data.sections[].items[].artists[].description	string	No	The official podcast of comedian Joe Rogan.
data.sections[].items[].artists[].externalUrl	string	No	https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk
data.sections[].items[].artists[].imageUrl	string	No	https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b
data.sections[].items[].artists[].images	array	No
data.sections[].items[].artists[].images[].height	integer	No	640
data.sections[].items[].artists[].images[].url	string	No	https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0
data.sections[].items[].artists[].images[].width	integer	No	640
data.sections[].items[].artists[].publisher	string	No	Joe Rogan
data.sections[].items[].artists[].subtitle	string	No	Joe Rogan
data.sections[].items[].artists[].title	string	No	The Joe Rogan Experience
data.sections[].items[].artists[].type	string	No	Podcast
data.sections[].items[].artists[].uri	string	No	spotify:show:4rOoJ6Egrf8K2IrywzwOMk
data.sections[].items[].attributes	object	No	[object Object]
data.sections[].items[].description	string	No	Your daily update of the most played tracks right now.
data.sections[].items[].externalUrl	string	No	https://open.spotify.com/playlist/37i9dQZEVXbLRQDuF5jeBpM
data.sections[].items[].imageUrl	string	No	https://charts-images.scdn.co/assets/locale_en/regional/daily/region_us_default.jpg
data.sections[].items[].images	array	No
data.sections[].items[].images[].height	integer	No	640
data.sections[].items[].images[].url	string	No	https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0
data.sections[].items[].images[].width	integer	No	640
data.sections[].items[].owner	spotify.SearchResultSummary	No
data.sections[].items[].owner.description	string	No	The official podcast of comedian Joe Rogan.
data.sections[].items[].owner.externalUrl	string	No	https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk
data.sections[].items[].owner.imageUrl	string	No	https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b
data.sections[].items[].owner.images	array	No
data.sections[].items[].owner.images[].height	integer	No	640
data.sections[].items[].owner.images[].url	string	No	https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0
data.sections[].items[].owner.images[].width	integer	No	640
data.sections[].items[].owner.publisher	string	No	Joe Rogan
data.sections[].items[].owner.subtitle	string	No	Joe Rogan
data.sections[].items[].owner.title	string	No	The Joe Rogan Experience
data.sections[].items[].owner.type	string	No	Podcast
data.sections[].items[].owner.uri	string	No	spotify:show:4rOoJ6Egrf8K2IrywzwOMk
data.sections[].items[].subtitle	string	No	Spotify
data.sections[].items[].title	string	No	Top 50 - USA
data.sections[].items[].type	string	No	Playlist
data.sections[].items[].uri	string	No	spotify:playlist:37i9dQZEVXbLRQDuF5jeBpM
data.sections[].title	string	No	Featured Charts
data.sections[].totalCount	integer	No	20
data.supportedCountries	array	No
data.supportedCountries[].code	string	No	us
data.supportedCountries[].name	string	No	United States
msg	unknown	No		Msg is the message that describes the result of the request @example "Request successful"

Code examples

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

curl -X GET "https://api.crawlora.net/api/v1/spotify/popular-by-country?country_code=us" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Responsible public web data workflows

Crawlora is designed for responsible structured public web data workflows. Customers are responsible for using Crawlora in compliance with applicable laws, third-party rights, target-platform rules, and Crawlora terms.

Read Crawlora terms

More Spotify endpoints Spotify platform Pricing Playground

Open in Playground Back to group

Retrieve Spotify popular by country

Overview

Request schema

Authentication

Billing

Infrastructure behavior

Response behavior

Error behavior

Failure responses

Example response

Code examples

Responsible public web data workflows

Related