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.
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:
curl "https://api.particle.pro/v1/podcasts/rankings" -H "X-API-Key: $PARTICLE_API_KEY"
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. |
List rankings
The workhorse list endpoint. With no parameters it returns the US Apple Top Podcasts overall chart.
curl "https://api.particle.pro/v1/podcasts/rankings" \
-H "X-API-Key: $PARTICLE_API_KEY"
{
"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"
}
| 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 or 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.
curl "https://api.particle.pro/v1/podcasts/the-daily/rankings" \
-H "X-API-Key: $PARTICLE_API_KEY"
{
"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
}
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.
curl "https://api.particle.pro/v1/podcasts/the-daily/rankings/summary" \
-H "X-API-Key: $PARTICLE_API_KEY"
{
"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": "" }
]
}
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:
{
"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.
curl "https://api.particle.pro/v1/podcasts/rankings/countries?source=apple" \
-H "X-API-Key: $PARTICLE_API_KEY"
{
"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.
{
"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.
curl "https://api.particle.pro/v1/podcasts/rankings/history?country=us&since=2026-04-01" \
-H "X-API-Key: $PARTICLE_API_KEY"
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.
curl "https://api.particle.pro/v1/podcasts/the-daily/rankings/history?country=us&since=2026-01-01" \
-H "X-API-Key: $PARTICLE_API_KEY"
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.
curl "https://api.particle.pro/v1/podcasts/rankings/movers?country=us&window_days=1" \
-H "X-API-Key: $PARTICLE_API_KEY"
{
"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
}
]
}
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 |
