Rankings - Particle API

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"

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 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.

curl "https://api.particle.pro/v1/podcasts/rankings" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response (truncated)

{
  "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.

curl "https://api.particle.pro/v1/podcasts/the-daily/rankings" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response (truncated)

{
  "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.

curl "https://api.particle.pro/v1/podcasts/the-daily/rankings/summary" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response

{
  "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:

{
  "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
}

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"

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.

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.

curl "https://api.particle.pro/v1/podcasts/rankings/movers?country=us&window_days=1" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response (truncated)

{
  "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`

Podcasts overview — full Podcast object.
Publishers — pivot from a chart entry’s publisher to its catalog.
Episodes — drill from a charting podcast into its episodes.
Ratings & reviews — user-generated star ratings and review text, the complement to chart position.

​Identifying a chart slot

​List rankings

​Query parameters

​About the linked podcast

​List current rankings for a podcast

​Summarize a podcast’s chart presence

​Discovery endpoints

​List sources

​List countries

​List categories

​History

​Chart slot history

​Per-podcast history

​Movers

​Query parameters

​Anatomy of a ranking row

​Choosing the right endpoint

​Related

Identifying a chart slot

List rankings

Query parameters

About the linked podcast

List current rankings for a podcast

Summarize a podcast’s chart presence

Discovery endpoints

List sources

List countries

List categories

History

Chart slot history

Per-podcast history

Movers

Query parameters

Anatomy of a ranking row

Choosing the right endpoint

Related