particle_podcast_get_rankings

Podcast chart rankings from Apple Podcasts and Spotify, in four modes:

chart (default): the current chart for a source/country/category slot, or — with podcast_slug — every chart slot that podcast currently holds.
movers: the biggest rank changes over window_days (risers, fallers, debuts, exits).
history: past snapshots for a chart slot, or — with podcast_slug — one podcast’s chart history over time.
slots: the valid slot values — every source, country, and category_slug with live chart data — so filter values are discovered, not guessed. source narrows the country/category listings; other filters are ignored.

Each row carries the matched podcast_slug when the chart entry is in the catalog — feed it into particle_podcast_resolve or any podcast tool. For a single podcast’s at-a-glance chart presence, particle_podcast_resolve with include: ["rankings"] is one call instead of two.

Inputs

Field	Type	Required	Default	Description
`mode`	string	no	`chart`	What to return: `chart`, `movers`, `history`, or `slots`.
`podcast_slug`	string	no	—	Podcast slug, internal ID, or numeric iTunes ID. With `mode=chart`: that podcast’s current chart appearances across every slot. With `mode=history`: that podcast’s chart history.
`source`	string	no	`apple`*	Ranking source platform. One of `apple`, `spotify`.
`country`	string	no	`us`*	ISO 3166-1 alpha-2 country code (e.g. `"us"`, `"gb"`, `"jp"`).
`category_slug`	string	no	—	Category slug (e.g. `"comedy"`, `"business"`). Omit for the overall chart.
`window_days`	integer (1–30)	no	1	Mode=movers only: comparison window in days (`1` = vs. yesterday).
`change`	string	no	`all`	Mode=movers only: filter by change type. One of `all`, `up`, `down`, `new`, `exit`.
`since`	string	no	—	Mode=history only: only snapshots captured on or after this ISO 8601 timestamp.
`until`	string	no	—	Mode=history only: only snapshots captured on or before this ISO 8601 timestamp.
`limit`	integer (1–100)	no	25	Rows per page.
`cursor`	string	no	—	Opaque pagination cursor. Not supported by `mode=movers`.

* The apple/us defaults apply to the slot-wide reads (chart and history without podcast_slug, and movers). The per-podcast views — chart or history with podcast_slug and no slot filters — span all sources and countries; set source/country explicitly to narrow them.

Output

A markdown document with ## Podcast rankings — <mode> (N rows) and a flat bullet list — one bullet per chart entry, formatted #<rank> Show name (podcast-slug) — <slot>, where <slot> is source/country/category. In movers mode each bullet appends [change ±delta]. In history mode each bullet appends @ YYYY-MM-DD (the snapshot date). The podcast-slug parenthetical appears only when the chart entry matched a catalog podcast — long-tail and international entries often haven’t, so the show name is the universal identity. When more pages exist, a horizontal rule and a **Cursor:** <value> line are appended. In slots mode the document is instead ## Chart slots with three sections: ### Sources (bullets with live row counts and capture dates), ### Categories (bullets formatted **slug** — Name [sources], with parent-category attribution for sub-categories), and ### Countries (a compact comma-separated list of ISO country codes). Sample (mode=movers, window_days=7, change=up, limit=3):

## Podcast rankings — movers (3 rows)

- #2 The Daily (the-daily) — apple/us [up +6]
- #5 Hard Fork (hard-fork) — apple/us [up +3]
- #9 Acquired (acquired) — apple/us [up +11]

Example

Agent calls: particle_podcast_get_rankings {
  "mode": "chart",
  "source": "apple",
  "country": "us",
  "category_slug": "business",
  "limit": 25
}

One podcast’s history over a window:

Agent calls: particle_podcast_get_rankings {
  "mode": "history",
  "podcast_slug": "all-in",
  "since": "2026-01-01"
}

REST equivalents by mode: GET /v1/podcasts/rankings or GET /v1/podcasts/{id}/rankings (chart), GET /v1/podcasts/rankings/movers (movers), GET /v1/podcasts/rankings/history or GET /v1/podcasts/{id}/rankings/history (history), GET /v1/podcasts/rankings/sources|countries|categories (slots).
For one podcast’s current chart positions inline, use particle_podcast_resolve with include: ["rankings"].

Get started

Tools

particle_podcast_get_rankings

Inputs

Output

Example

​Inputs

​Output

​Example

​Related

Inputs

Output

Example

Related