---
title: "Retrieve Spotify podcast charts"
method: GET
path: "/spotify-podcasts/charts"
tags: ["SpotifyPodcasts"]
---

# Retrieve Spotify podcast charts

`GET /spotify-podcasts/charts`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/spotify-podcasts/charts`
- Auth: API key in header `x-api-key`

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.

## Query parameters

- `chart` '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'
- `region` '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'
- `limit` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- SpotifyChartsResponseDoc
  - `code` integer: Code is the HTTP status code or a custom code used to indicate the result of the request @example 200
  - `data` SpotifyChartResponse
    - `chart` string: Chart identifier that was requested, for example `top-podcasts`.
    - `chartName` string: Display name of the chart.
    - `chartType` string: Whether the chart is an overall `chart` or a `category` chart.
    - `items` SpotifyChartItem[]: Chart entries, ordered by rank.
      - `description` string: Description text of the chart entry.
      - `episodeDescription` string: Description text of the episode, for episode charts.
      - `episodeExternalUrl` string: Link to the episode on open.spotify.com, for episode charts.
      - `episodeImageUrl` string: URL of the episode's cover image, for episode charts.
      - `episodeName` string: Episode title as Spotify shows it, for episode charts.
      - `episodeUri` string: Spotify URI of the episode, for episode charts.
      - `externalUrl` string: Link to the chart entry on open.spotify.com.
      - `imageUrl` string: URL of the cover image for the chart entry.
      - `name` string: Title of the chart entry (episode title for episode charts, otherwise show title).
      - `publisher` string: Name of the publisher of the show.
      - `rank` integer: Position of the entry in the chart, starting at 1.
      - `rankMove` string: Change in rank since the previous chart period, as Spotify labels it, for example `UNCHANGED`.
      - `showDescription` string: Description text of the show.
      - `showExternalUrl` string: Link to the show on open.spotify.com.
      - `showImageUrl` string: URL of the show's cover image.
      - `showName` string: Show title as Spotify shows it.
      - `showPublisher` string: Name of the show's publisher.
      - `showUri` string: Spotify URI of the show.
      - `uri` string: Spotify URI of the chart entry (an episode for episode charts, otherwise a show).
    - `limit` integer: Maximum number of chart entries requested.
    - `meta` SpotifyChartMeta
      - `count` integer: Number of chart entries returned.
      - `fetchedAt` string: Time the data was fetched, in UTC (RFC 3339).
      - `sourceUrl` string: URL the data was read from.
    - `region` string: Region code the chart was loaded for.
    - `regionName` string: Name of the chart region.
  - `msg` unknown

## Other responses

- `400`: Missing or invalid parameters
- `429`: Rate limit exceeded
- `503`: Spotify upstream request failed

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/0497899e2016?raw)