---
title: "Summarize a podcast's chart presence"
method: GET
path: "/v1/podcasts/{id}/rankings/summary"
tags: ["Podcast Rankings", "tier:premium"]
---

# Summarize a podcast's chart presence

`GET /v1/podcasts/{id}/rankings/summary`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/podcasts/{id}/rankings/summary`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns a one-call aggregate of the podcast's current chart presence: the number of distinct chart slots, sources, countries, and categories it appears on, plus the single best (lowest-numbered) rank it currently holds and a per-source breakdown.

## Path parameters

- `id` string, required: Podcast slug, internal ID, or numeric iTunes ID.

## Response `200`

OK

- PodcastRankingsSummary
  - `appearances_by_source` SourceAppearanceStat[], nullable, required: Per-source breakdown of chart presence and best rank.
    - `best_category_slug` string
    - `best_country` string
    - `best_rank` integer, required
    - `chart_count` integer, required
    - `source` 'apple' | 'spotify', required
  - `best_rank` PodcastRankingHandle
    - `captured_at` string, date-time, required
    - `category_slug` string
    - `chart_type` 'top_podcasts', required
    - `country` string
    - `rank` integer, required
    - `source` 'apple' | 'spotify', required
  - `category_count` integer, required: Number of distinct categories currently charting this podcast.
  - `chart_count` integer, required: Number of distinct chart slots (source × country × category) on which this podcast currently appears.
  - `country_count` integer, required: Number of distinct countries currently charting this podcast.
  - `podcast` PodcastCompact, required
    - `best_rank` PodcastRankingHandle
      - `captured_at` string, date-time, required
      - `category_slug` string
      - `chart_type` 'top_podcasts', required
      - `country` string
      - `rank` integer, required
      - `source` 'apple' | 'spotify', required
    - `id` string, required: Podcast ID
    - `image_url` string: Cover image URL
    - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints.
    - `publisher` PodcastPublisherCompact
      - `id` string, required: Publisher ID
      - `name` string, required: Publisher name
      - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs).
    - `slug` string: Human-readable slug identifier
    - `title` string, required: Podcast title
  - `source_count` integer, required: Number of distinct sources currently charting this podcast.

## Other responses

- `402`: Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent.
- `default`: Error

---

[API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)