Spotify API endpoint
Returns Spotify home shelves and items. Caller-supplied Spotify bearer or client tokens are not required.
/spotify/homePath/query/body parameters:
time_zone query string, optional. IANA time zone used by Spotify home personalization. Defaults to UTC.sp_t query string, optional. Spotify session token value. A random UUID is generated when omitted.facet query string, optional. Spotify home facet.section_items_limit query integer, optional. Per-section item limit, clamped to 1-50. Defaults to 10.include_episode_content_ratings_v2 query boolean, optional. Includes Spotify episode content ratings v2 when requested.Notable response behavior:
503.| Field | Filled in, of 5 checked | Values in the sample |
|---|---|---|
| uri | 5 | “spotify:section:0JQ5DB5E8N831KzFzsBBQ2” and 4 other values |
| type | 5 | HomeGenericSectionData in all 5 |
| title | 5 | “Trending songs” and 4 other values |
| totalCount | 5 | 4 to 50, median 30 |
| items | 5 | median 10 entries |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| time_zone | string | No | IANA time zone used by Spotify home personalization | Asia/Shanghai | |
| sp_t | string | No | Optional Spotify session token. A random UUID is generated when omitted | 00000000-0000-4000-8000-000000000000 | |
| facet | string | No | Optional Spotify home facet | ||
| section_items_limit | integer | No | Per-section item limit, clamped to 1-50 | 10 | |
| include_episode_content_ratings_v2 | boolean | No | Include Spotify episode content ratings v2 | false | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/spotify/home?include_episode_content_ratings_v2=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"timeZone": "UTC",
"greeting": "Good evening",
"sections": [
{
"title": "Shows to try",
"items": [
{
"uri": "spotify:show:1QQJ7FElLE0K6CIfZNCxU4",
"type": "Podcast",
"title": "Example Show",
"imageUrl": "https://i.scdn.co/image/example",
"externalUrl": "https://open.spotify.com/show/1QQJ7FElLE0K6CIfZNCxU4"
}
]
}
],
"meta": {
"operationName": "home",
"appVersion": "1.2.90.373.g86862e17",
"sectionCount": 1,
"fetchedAt": "2026-05-13T15:22:41Z"
}
}
}Request schema
No body schema
Response schema
#/definitions/spotify.homeResponseDoc
| 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.HomeResponse | No | ||||
| data.facet | string | No | music | Home page filter that was applied, for example `music`. | ||
| data.greeting | string | No | Good afternoon | Greeting Spotify shows at the top of the home page, for example `Good afternoon`. | ||
| 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:12Z | Time the data was fetched, in UTC (RFC 3339). | ||
| data.meta.operationName | string | No | home | Name of the Spotify web player operation that returned the data. | ||
| data.meta.sectionCount | integer | No | 8 | Number of sections returned. | ||
| data.sections | array | No | Home page sections, in display order. | |||
| data.sections[].items | array | No | Items returned for this section. | |||
| data.sections[].items[].description | string | No | The official podcast of comedian Joe Rogan. | Description text of the item. | ||
| data.sections[].items[].externalUrl | string | No | https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk | Link to the item on open.spotify.com. | ||
| data.sections[].items[].imageUrl | string | No | https://i.scdn.co/image/ab67656300005f1f54e6837957803d762a3f4d2b | URL of the main image for the item. | ||
| data.sections[].items[].images | array | No | Images available for the item, with their sizes. | |||
| data.sections[].items[].images[].height | integer | No | 640 | Image height in pixels. | ||
| data.sections[].items[].images[].url | string | No | https://i.scdn.co/image/ab6765630000ba8ab0484f8ee2933eceab32bac0 | URL of the image. | ||
| data.sections[].items[].images[].width | integer | No | 640 | Image width in pixels. | ||
| data.sections[].items[].publisher | string | No | Joe Rogan | Publisher or creator name of the item. | ||
| data.sections[].items[].subtitle | string | No | Joe Rogan | Secondary line shown under the item title, such as the creator name. | ||
| data.sections[].items[].title | string | No | The Joe Rogan Experience | Item title as Spotify shows it. | ||
| data.sections[].items[].type | string | No | Podcast | Kind of item as Spotify labels it, for example `Podcast`. | ||
| data.sections[].items[].uri | string | No | spotify:show:4rOoJ6Egrf8K2IrywzwOMk | Spotify URI of the item. | ||
| data.sections[].subtitle | string | No | Recommended shows | Secondary line shown under the section heading. | ||
| data.sections[].title | string | No | Popular podcasts | Section heading as Spotify shows it. | ||
| data.sections[].totalCount | integer | No | 20 | Total number of items in the section on Spotify. | ||
| data.sections[].type | string | No | BrowseGenericSectionData | Kind of section as Spotify labels it. | ||
| data.sections[].uri | string | No | spotify:section:0JQ5IMCbQBLqNPkcmYxQPQ | Spotify URI of the section. | ||
| data.timeZone | string | No | UTC | Time zone the home page was personalized for. | ||
| 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/home?include_episode_content_ratings_v2=true" \
-H "x-api-key: $CRAWLORA_API_KEY"