Ratings & reviews

The ratings endpoints expose user-generated ratings (1–5 stars) and reviews (optional free-text title and body) from third-party platforms. Today the source is Apple Podcasts customer reviews, covering the us, gb, ca, au, nz, and ie storefronts.

These endpoints surface listener opinion. For chart position (where a show ranks on Apple/Spotify Top Podcasts) use /v1/podcasts/rankings instead.

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

returns the most recent ratings for the podcast across every platform and locale, newest first. Use these endpoints when you want to:

Display a podcast’s review history with star scores, titles, and body text.
Render the per-platform star average + histogram on a podcast detail page.
Pull a short narrative summary of what listeners are saying — without parsing hundreds of reviews yourself.
Compare reception across countries (e.g. US vs UK reviews for the same show).

Anatomy of a rating

Field	Description
`id`	Stable identifier for this rating.
`platform_slug`	Canonical platform identifier. Today only `apple`.
`locale`	Platform-specific locale code (e.g. Apple storefront `us`, `gb`). Empty for platforms without a locale dimension.
`platform_rating_id`	Platform-native identifier for the rating.
`stars`	Integer 1–5 star score.
`title`	Review title when present.
`body`	Review body when present.
`author_display_name`	Display name the reviewer chose on the platform.
`author_uri`	Reviewer profile URL on the platform, when present.
`posted_at`	RFC 3339 timestamp of when the rating was posted on the source.
`link_href`	Source-platform link for the individual rating, when present.

Optional fields are omitted when no data is available.

List ratings for a podcast

Returns the most recent ratings for the podcast, newest first.

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

const res = await fetch(
  "https://api.particle.pro/v1/podcasts/the-daily/ratings",
  { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data, has_more, cursor } = await res.json();

res = httpx.get(
    "https://api.particle.pro/v1/podcasts/the-daily/ratings",
    headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
body = res.json()

Response (truncated)

{
  "data": [
    {
      "id": "0RZ7y1DAY01",
      "platform_slug": "apple",
      "locale": "us",
      "platform_rating_id": "14110653821",
      "stars": 5,
      "title": "Required daily listening",
      "body": "I've started every morning with this since 2018…",
      "author_display_name": "morningcommuter",
      "author_uri": "https://itunes.apple.com/us/reviews/id17563210",
      "posted_at": "2026-05-26T22:02:40Z",
      "link_href": "https://itunes.apple.com/us/review?id=1535809341&type=Podcast"
    },
    {
      "id": "0RZ7y1DAY02",
      "platform_slug": "apple",
      "locale": "gb",
      "platform_rating_id": "14109001233",
      "stars": 2,
      "title": "Ad-heavy lately",
      "body": "Loved the format for years but the ad load has crept up…",
      "author_display_name": "tubebreezeway",
      "posted_at": "2026-05-26T11:14:08Z"
    }
    // …25 entries by default; paginate with `cursor`
  ],
  "has_more": true,
  "cursor": "r.AQAAAGQ"
}

Query parameters

Parameter	Default	Description
`platform_slug`	—	Restrict to one platform.
`locale`	—	Restrict to one platform locale (Apple storefront code).
`min_stars`	—	Lower bound (inclusive) on the star score, 1–5.
`since`	—	Lower bound on `posted_at` (RFC 3339).
`until`	—	Upper bound on `posted_at` (RFC 3339).
`limit`	`25`	Page size, 1–100.
`cursor`	—	Opaque cursor from the previous response.

Summarize a podcast’s ratings

A one-call aggregate: the star average and histogram for each (platform, locale) the podcast is rated on, a combined cross-source roll-up, plus the latest narrative summary when available.

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

const res = await fetch(
  "https://api.particle.pro/v1/podcasts/the-daily/ratings/summary",
  { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const summary = await res.json();

Response

{
  "podcast_id": "0RZ7y1ABC",
  "entries": [
    {
      "platform_slug": "apple",
      "locale": "us",
      "rating_count": 78492,
      "rating_average": 4.59,
      "histogram": { "stars_1": 1820, "stars_2": 1456, "stars_3": 3712, "stars_4": 13105, "stars_5": 58399 },
      "computed_at": "2026-05-27T18:14:02Z"
    },
    {
      "platform_slug": "apple",
      "locale": "gb",
      "rating_count": 6418,
      "rating_average": 4.43,
      "histogram": { "stars_1": 188, "stars_2": 220, "stars_3": 412, "stars_4": 1390, "stars_5": 4208 },
      "computed_at": "2026-05-27T18:14:02Z"
    }
    // …one entry per (platform, locale) the podcast has been rated on
  ],
  "combined": {
    "platform_slug": "",
    "locale": "",
    "rating_count": 94782,
    "rating_average": 4.59,
    "histogram": { "stars_1": 2154, "stars_2": 1798, "stars_3": 4350, "stars_4": 15842, "stars_5": 70638 },
    "computed_at": "2026-05-27T18:14:02Z"
  },
  "sentiment": {
    "platform_slug": "apple",
    "locale": "",
    "summary_text": "Listeners consistently praise the host's calm pacing and the show's reliable five-day cadence; the most common recent criticism is a perceived uptick in ad load. A small but vocal contingent has been frustrated with topic selection over the past two months. Reviews remain overwhelmingly positive overall.",
    "window_start": "2026-04-28T00:00:00Z",
    "window_end": "2026-05-26T22:02:40Z",
    "rating_count_in_window": 312,
    "generated_at": "2026-05-27T08:00:00Z"
  }
}

entries carries one row per (platform, locale) the podcast has been rated on, or null when the podcast hasn’t been rated yet. combined is the count-weighted roll-up across every entry — platform_slug and locale are empty to signal the cross-source view — and is null when there’s nothing to aggregate. sentiment is a short narrative summary (typically 2–5 sentences) over the most recent ratings, intended for non-technical readers — analysts, brand and PR teams, talent agents, journalists, producers. It paraphrases what listeners are saying rather than quoting individual reviews, and is null when one hasn’t been generated yet (e.g. on freshly ingested podcasts or shows with very few ratings). Returns 404 when the podcast can’t be resolved by slug, ID, or numeric iTunes ID.

Sentiment summary fields

Field	Description
`summary_text`	The narrative paragraph.
`window_start`	Earliest `posted_at` in the ratings window the summary covers.
`window_end`	Latest `posted_at` in the ratings window the summary covers.
`rating_count_in_window`	How many ratings the summary aggregates.
`generated_at`	When the summary was produced.
`platform_slug`, `locale`	Scope of the summary. Today summaries are platform-scoped (Apple) and cross-locale (empty `locale`).

Choosing the right endpoint

You want to…	Use this
Show a podcast’s review history with stars, titles, and text	`GET /v1/podcasts/{id}/ratings`
Render a star average + histogram per platform	`GET /v1/podcasts/{id}/ratings/summary`
Render a single overall star average (across every platform/locale)	`GET /v1/podcasts/{id}/ratings/summary` → `combined`
Surface a short narrative of what listeners are saying lately	`GET /v1/podcasts/{id}/ratings/summary` → `sentiment`
Get chart positions (Apple/Spotify rankings)	`GET /v1/podcasts/rankings`
Get the podcast’s own metadata (title, publisher, description, RSS feed)	`GET /v1/podcasts/{id}`
Pull a podcast’s third-party platform IDs and audience sizes	`GET /v1/podcasts/{id}/external-links`

Podcasts overview — full Podcast object and the other sub-resources.
Rankings — Apple and Spotify chart positions; the complementary signal to user ratings.
External links — platform-level audience-size attributes (followers, subscribers) on Spotify, YouTube, etc.

Getting started

Podcasts

Companies

Knowledge graph

Alerts

Errors

Anatomy of a rating

List ratings for a podcast

Query parameters

Summarize a podcast’s ratings

Sentiment summary fields

Choosing the right endpoint

​Anatomy of a rating

​List ratings for a podcast

​Query parameters

​Summarize a podcast’s ratings

​Sentiment summary fields

​Choosing the right endpoint

​Related

Anatomy of a rating

List ratings for a podcast

Query parameters

Summarize a podcast’s ratings

Sentiment summary fields

Choosing the right endpoint

Related