> ## 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.
# Ratings & reviews
> Per-podcast user-generated 1–5 star ratings and review text, a numeric aggregate per (platform, locale), and a periodic narrative summary of listener sentiment.
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`](/podcasts/rankings) instead.
```bash theme={"dark"}
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.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/the-daily/ratings" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
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();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/podcasts/the-daily/ratings",
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
body = res.json()
```
```jsonc Response (truncated) theme={"dark"}
{
"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.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/the-daily/ratings/summary" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
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();
```
```jsonc Response theme={"dark"}
{
"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`](/podcasts/rankings) |
| Get the podcast's own metadata (title, publisher, description, RSS feed) | [`GET /v1/podcasts/{id}`](/podcasts/overview) |
| Pull a podcast's third-party platform IDs and audience sizes | [`GET /v1/podcasts/{id}/external-links`](/podcasts/external-links) |
## Related
* [Podcasts overview](/podcasts/overview) — full Podcast object and the other sub-resources.
* [Rankings](/podcasts/rankings) — Apple and Spotify chart positions; the complementary signal to user ratings.
* [External links](/podcasts/external-links) — platform-level audience-size attributes (followers, subscribers) on Spotify, YouTube, etc.