> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.
# Rankings
> Browse the live Apple and Spotify podcast charts — top podcasts by country and category, per-podcast chart presence, historical snapshots, and trending movers.
The rankings endpoints expose podcast chart data captured daily from Apple Podcasts and Spotify. We refresh **roughly 1.7 million chart positions every day** across 170+ countries × 100+ categories × ranks 1–200, so the data you query is always the live snapshot — yesterday's charts are already historical and addressable through the history endpoints.
Every chart slot is identified by the same four-field vocabulary — **source**, **chart\_type**, **country**, **category\_slug** — and that vocabulary works the same way on every endpoint. Learn it once and you know the whole surface.
The simplest call needs no parameters at all:
```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/rankings" -H "X-API-Key: $PARTICLE_API_KEY"
```
returns the first page of the **US Apple Top Podcasts** chart, ordered by rank ascending. Charts run to rank 200; the default page size is 25 (raise it up to 100 with `limit`, or paginate with `cursor`).
Use these endpoints when you want to:
* Render a chart leaderboard for any country or category.
* See where a specific podcast currently ranks across every source/country/category.
* Track historical chart positions over time.
* Surface trending podcasts — chart debuts, departures, and the biggest rank movers.
## Identifying a chart slot
A "chart slot" is the unit of analysis: one (source × chart\_type × country × category) tuple, refreshed daily. Every browse and history endpoint accepts the same query parameters to pin or scope a slot:
| Parameter | Default | Description |
| --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `source` | `apple` | Ranking source platform: `apple` or `spotify`. |
| `chart_type` | `top_podcasts` | Chart variant within the source. Currently only `top_podcasts` is available. |
| `country` | `us` | Lowercase ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`, `jp`). |
| `category_slug` | — | Category slug (e.g. `comedy`, `business`). Universal across sources. **Omit for the overall "Top Podcasts" chart.** |
Use the [discovery endpoints](#discovery-endpoints) to enumerate the available sources, countries, and categories.
## List rankings
The workhorse list endpoint. With no parameters it returns the US Apple Top Podcasts overall chart.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/rankings" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch("https://api.particle.pro/v1/podcasts/rankings", {
headers: { "X-API-Key": process.env.PARTICLE_API_KEY },
});
const { data, has_more, cursor } = await res.json();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/podcasts/rankings",
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
body = res.json()
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"id": "0RZ7y1DAY01",
"source": "apple",
"chart_type": "top_podcasts",
"country": "us",
"rank": 1,
"chart_total": 200,
"captured_at": "2026-05-09T03:07:21Z",
"is_current": true,
"external_id": "1581410252",
"external_url": "https://podcasts.apple.com/us/podcast/the-daily/id1581410252",
"show": {
"name": "The Daily",
"publisher": "The New York Times",
"language": "en-US",
"image_url": "https://is1-ssl.mzstatic.com/.../600x600.jpg",
"total_episodes": 1842,
"genres": [{ "external_id": "1489", "name": "News" }]
},
"podcast": {
"id": "0RZ7y1ABC",
"slug": "the-daily",
"title": "The Daily",
"image_url": "https://cdn.particle.pro/podcasts/the-daily.jpg"
}
}
// …25 entries (the default page size; charts run to rank 200, paginate with `cursor`)
],
"has_more": true,
"cursor": "r.AQAAAGQ"
}
```
Common shapes of the call:
| Goal | Call |
| ------------------------------------ | ----------------------------------------------------------- |
| UK Apple Top Comedy | `GET /v1/podcasts/rankings?country=gb&category_slug=comedy` |
| US Spotify Top Podcasts | `GET /v1/podcasts/rankings?source=spotify` |
| Just the top 10 of any chart | `GET /v1/podcasts/rankings?max_rank=10` |
| Ranks 11–20 of a chart | `GET /v1/podcasts/rankings?min_rank=11&max_rank=20` |
| Where does a specific podcast chart? | `GET /v1/podcasts/rankings?podcast_id=the-daily` |
| Where does it chart in the UK? | `GET /v1/podcasts/rankings?podcast_id=the-daily&country=gb` |
### Query parameters
| Parameter | Default | Description |
| --------------- | -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `source` | `apple` | Source platform. |
| `chart_type` | `top_podcasts` | Chart variant. |
| `country` | `us` | Country code. |
| `category_slug` | — | Category slug. Omit for the overall chart. |
| `podcast_id` | — | Slug, ID, or numeric iTunes ID. Restricts results to one podcast (and skips the implicit "overall only" default). |
| `min_rank` | — | Optional inclusive rank floor (1–500). |
| `max_rank` | — | Optional inclusive rank ceiling (1–500). |
| `limit` | `25` | Page size, 1–100. |
| `cursor` | — | Opaque cursor from the previous response. |
### About the linked podcast
We track tens of thousands of the highest-ranked podcasts in the catalog — every show that consistently charts is in there, with full transcripts, sponsors, mentions, and the rest of the Particle Pro surface. Those rows carry a `podcast` field that links straight into the catalog (`GET /v1/podcasts/{slug}` and friends). For the long tail of intermittent or hyper-local entries — chart slots in 170+ countries surface a lot of one-day wonders — `podcast` is omitted and the response still carries a complete `show` block with name, publisher, artwork, and feed URL. Treat `show` as the canonical identity for every row and use `podcast` to cross-link into the catalog whenever it's present.
## List current rankings for a podcast
Returns every live chart slot a podcast appears on, across sources and countries. Rows are clustered by (source, country, category) — overall charts come before sub-categories within each (source, country) group — so iterating the response naturally walks the podcast's footprint without re-sorting.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/the-daily/rankings" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch(
"https://api.particle.pro/v1/podcasts/the-daily/rankings",
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{ "source": "apple", "country": "us", "category": null, "rank": 1, "captured_at": "2026-05-09T03:07:21Z", /* … */ },
{ "source": "apple", "country": "us", "category": { "slug": "news", "name": "News", "external_id": "1489" }, "rank": 1, /* … */ },
{ "source": "apple", "country": "gb", "category": null, "rank": 4, /* … */ },
{ "source": "spotify", "country": "us", "category": null, "rank": 5, /* … */ }
// …more chart slots
],
"has_more": false
}
```
Returns 404 when the podcast can't be resolved by slug, ID, or numeric iTunes ID. Pagination is opt-in via `limit` and `cursor`; by default every chart slot the podcast occupies is returned in one response (typically dozens, occasionally a few hundred for very popular shows charting in many countries).
## Summarize a podcast's chart presence
A one-call aggregate: how many distinct chart slots, sources, countries, and categories the podcast is on right now, plus its single best (lowest-numbered) rank.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/the-daily/rankings/summary" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```jsonc Response theme={"dark"}
{
"podcast": {
"id": "0RZ7y1ABC",
"slug": "the-daily",
"title": "The Daily"
},
"chart_count": 47,
"source_count": 2,
"country_count": 18,
"category_count": 4,
"best_rank": {
"source": "apple",
"chart_type": "top_podcasts",
"country": "us",
"rank": 1,
"captured_at": "2026-05-09T03:07:21Z"
},
"appearances_by_source": [
{ "source": "apple", "chart_count": 35, "best_rank": 1, "best_country": "us", "best_category_slug": "" },
{ "source": "spotify", "chart_count": 12, "best_rank": 4, "best_country": "us", "best_category_slug": "" }
]
}
```
When multiple chart placements tie at the same rank, `best_rank` (and each `appearances_by_source[*].best_*`) prefers the higher-priority market — `us > gb > ca > au > de > fr > es > it > mx > br > jp > ie > nl > se > nz`, then alphabetical. A US #1 always wins over a tied #1 in a smaller market. Within a country, the overall chart wins over a sub-category placement.
## Discovery endpoints
These let you enumerate which sources, countries, and categories actually have data right now — without paginating through millions of rows.
### List sources
`GET /v1/podcasts/rankings/sources` returns each `(source, chart_type)` pair currently available, with row counts and freshness:
```jsonc theme={"dark"}
{
"data": [
{ "source": "apple", "chart_type": "top_podcasts", "current_row_count": 1737573, "latest_captured_at": "2026-05-09T03:07:21Z" },
{ "source": "spotify", "chart_type": "top_podcasts", "current_row_count": 11100, "latest_captured_at": "2026-05-09T06:14:56Z" }
],
"has_more": false
}
```
### List countries
`GET /v1/podcasts/rankings/countries` returns every country with current data. Each entry carries the human-readable name (when known) and the count of distinct chart slots.
```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/rankings/countries?source=apple" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```jsonc theme={"dark"}
{
"data": [
{ "code": "us", "name": "United States", "current_chart_count": 18, "sources": ["apple", "spotify"] },
{ "code": "gb", "name": "United Kingdom", "current_chart_count": 17, "sources": ["apple"] }
// …
],
"has_more": false
}
```
### List categories
`GET /v1/podcasts/rankings/categories` returns every category currently represented. For Apple sub-categories the response includes `parent_slug` so you can render the hierarchy.
```jsonc theme={"dark"}
{
"data": [
{ "slug": "society-culture", "name": "Society & Culture", "external_id": "1324", "current_chart_count": 172, "sources": ["apple"] },
{ "slug": "self-improvement", "name": "Self-Improvement", "external_id": "1500", "parent_slug": "education", "current_chart_count": 172, "sources": ["apple"] },
{ "slug": "comedy", "name": "Comedy", "external_id": "1303", "current_chart_count": 198, "sources": ["apple", "spotify"] }
// …
],
"has_more": false
}
```
`external_id` is the source-native category id. When a category is reported by multiple sources (Apple's iTunes genre id "1303" and Spotify's slug-as-id "comedy" both map to `comedy`), the response prefers Apple's id; pin a single source via `?source=spotify` if you need the Spotify-native form. `category_slug` is the universal handle and works as a filter on every endpoint regardless of source.
## History
History endpoints reach beyond the live snapshot to surface chart positions over time.
### Chart slot history
Returns historical snapshots for a chart slot, ordered most-recent first. Combine with `since` / `until` to bound the range.
```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/rankings/history?country=us&since=2026-04-01" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
Each row in the response is a `PodcastRanking` object — the same shape as the list endpoint, just with older `captured_at` values. Pin `podcast_id` to filter to a single podcast within the slot.
### Per-podcast history
Returns the full historical chart record for a single podcast, optionally narrowed by chart slot or date range.
```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/the-daily/rankings/history?country=us&since=2026-01-01" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
When `category_slug` is set on this endpoint, `source` must also be set (returns 422 otherwise) — category slugs aren't unique across sources at the wire level, so a Spotify "comedy" filter would otherwise silently exclude Apple matches and vice versa.
## Movers
`GET /v1/podcasts/rankings/movers` returns the chart entries whose rank changed between the live snapshot and a comparison snapshot `window_days` ago. Use it to surface trending movement, new arrivals, and departures — all from one endpoint.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/rankings/movers?country=us&window_days=1" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch(
"https://api.particle.pro/v1/podcasts/rankings/movers?country=us&window_days=1",
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"source": "apple",
"chart_type": "top_podcasts",
"country": "us",
"rank": 4,
"show": { "name": "Smartless", "publisher": "Wondery" },
"change": "up",
"delta": 9, // rose from #13 to #4
"previous_snapshot": { "rank": 13, /* full PodcastRanking shape — same fields as the row above, omitted for brevity */ }
},
{
"source": "apple",
"country": "us",
"rank": 7,
"show": { "name": "New Show", "publisher": "Indie" },
"change": "new" // chart debut
},
{
"source": "apple",
"country": "us",
"rank": 200, // last seen rank
"show": { "name": "Stale Show", "publisher": "…" },
"change": "exit" // fell off the chart
}
]
}
```
The `change` filter narrows to a single change type:
| `change` | Meaning |
| --------------- | ----------------------------------------------------------------- |
| `all` (default) | Every change type below. Stable rows are always excluded. |
| `up` | Entries whose rank improved (lower number). |
| `down` | Entries whose rank dropped. |
| `new` | Entries that appeared on the chart since the comparison snapshot. |
| `exit` | Entries that fell off the chart. |
### Query parameters
| Parameter | Default | Description |
| -------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `source`, `chart_type`, `country`, `category_slug` | `apple`, `top_podcasts`, `us`, — | Standard chart-slot filters. |
| `window_days` | `1` | Comparison window in days, 1–30. The comparison snapshot is the most recent retired snapshot closest in time to (now − window\_days). |
| `change` | `all` | Change-type filter. |
| `limit` | `25` | Maximum movers to return, 1–100. |
## Anatomy of a ranking row
| Field | Description |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `id` | Stable identifier for this specific snapshot of this entry. |
| `source` | `apple` or `spotify`. |
| `chart_type` | `top_podcasts`. |
| `country` | Lowercase ISO 3166-1 alpha-2 code. |
| `category` | `{slug, name, external_id, parent_slug}` or null for the overall chart. |
| `rank` | 1-based position. |
| `previous_rank` | Source-reported prior rank when the source provides it. Apple does not currently populate this. |
| `growth_indicator` | Source-supplied trend hint (e.g. `up`, `down`). |
| `chart_total` | Length of the chart at this snapshot (typically 200). |
| `captured_at` | When we captured the snapshot (UTC). Stable for every row in the same snapshot. |
| `source_updated_at` | Timestamp the source itself reported for the chart, when present. |
| `external_id` | Source-native chart entry id. Stable across captures. |
| `external_url` | Canonical URL on the source platform. |
| `show` | Show metadata captured with the entry. **Always present**, even when `podcast` is absent. |
| `podcast` | Compact podcast object when matched in our catalog; absent otherwise. |
## Choosing the right endpoint
| You want to… | Use this |
| --------------------------------------- | ------------------------------------------------ |
| The current US Apple Top Podcasts | `GET /v1/podcasts/rankings` |
| Top podcasts in another country | `GET /v1/podcasts/rankings?country=gb` |
| Top podcasts in a category | `GET /v1/podcasts/rankings?category_slug=comedy` |
| Where one podcast charts right now | `GET /v1/podcasts/{id}/rankings` |
| One-call podcast popularity card | `GET /v1/podcasts/{id}/rankings/summary` |
| What sources/countries/categories exist | The three discovery endpoints |
| Historical snapshots of a chart | `GET /v1/podcasts/rankings/history` |
| Historical rank of a podcast | `GET /v1/podcasts/{id}/rankings/history` |
| Trending movers / debuts / departures | `GET /v1/podcasts/rankings/movers` |
## Related
* [Podcasts overview](/podcasts/overview) — full Podcast object.
* [Publishers](/podcasts/publishers) — pivot from a chart entry's publisher to its catalog.
* [Episodes](/podcasts/episodes) — drill from a charting podcast into its episodes.
* [Ratings & reviews](/podcasts/ratings) — user-generated star ratings and review text, the complement to chart position.