Skip to main content

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

FieldDescription
idStable identifier for this rating.
platform_slugCanonical platform identifier. Today only apple.
localePlatform-specific locale code (e.g. Apple storefront us, gb). Empty for platforms without a locale dimension.
platform_rating_idPlatform-native identifier for the rating.
starsInteger 1–5 star score.
titleReview title when present.
bodyReview body when present.
author_display_nameDisplay name the reviewer chose on the platform.
author_uriReviewer profile URL on the platform, when present.
posted_atRFC 3339 timestamp of when the rating was posted on the source.
link_hrefSource-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"
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

ParameterDefaultDescription
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).
limit25Page 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"
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 or ID.

​
Sentiment summary fields

FieldDescription
summary_textThe narrative paragraph.
window_startEarliest posted_at in the ratings window the summary covers.
window_endLatest posted_at in the ratings window the summary covers.
rating_count_in_windowHow many ratings the summary aggregates.
generated_atWhen the summary was produced.
platform_slug, localeScope 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 textGET /v1/podcasts/{id}/ratings
Render a star average + histogram per platformGET /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 latelyGET /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 sizesGET /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.