particle_podcast_get_rankings

Podcast chart rankings from Apple Podcasts and Spotify — current charts, biggest movers, and ranking history.

Podcast chart rankings from Apple Podcasts and Spotify, in three 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.

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, or history.
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.

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

Related

• 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).
• For one podcast’s current chart positions inline, use particle_podcast_resolve with include: ["rankings"].