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

# Publisher Brand Suitability

> Publisher-level rollups of IAB Tech Lab Brand Safety & Suitability Framework verdicts — tier composition, per-category exposure, cross-publisher leaderboards, and category-pivot views for regulated brands.

The per-podcast [brand suitability assessment](/podcasts/suitability) is the unit of measurement; the publisher rollups described here are the unit of *decision*. Advertisers don't buy a single show — they buy across a publisher's catalog. A buying decision needs a per-publisher composition view, a way to rank publishers against each other, and a way to pivot on the categories that matter for a specific brand.

These endpoints expose four views over the same underlying assessments:

1. **`GET /v1/podcasts/publishers/{id}/suitability`** — the composite **profile** for one publisher. Tier composition, per-category exposure, top concerns. The headline endpoint.
2. **`GET /v1/podcasts/publishers/{id}/suitability/podcasts`** — drill down into a publisher to see which specific podcasts are concerning, filterable by tier, category, prevalence, and treatment.
3. **`GET /v1/podcasts/suitability/publishers/leaderboard`** — cross-publisher ranking by safest, riskiest, most-placeable, or most-analyzed.
4. **`GET /v1/podcasts/suitability/categories/{code}/publishers`** — pivot on a single GARM category and rank publishers by exposure. The killer view for regulated brands (alcohol, gambling, cannabis, family).

<Note>Per-podcast endpoints — `GET /v1/podcasts/{id}/suitability` and the embedded `suitability_tier` on `GET /v1/podcasts/{id}` — remain the source of truth for an individual show. The publisher endpoints aggregate from those same assessments.</Note>

## Coverage caveat

Suitability analyses are still being backfilled across the catalog. At time of writing, \~10% of the catalog has been assessed, biased toward more popular shows. Every aggregate response surfaces a `coverage.analyzed_coverage` (0..1 share) and a `coverage.quality` enum (`LOW` \< 0.3, `MEDIUM` 0.3–0.7, `HIGH` ≥ 0.7) so callers can weight the rollup against the underlying sample.

Cross-publisher rankings additionally accept a `min_analyzed_podcasts` parameter (default `5`) so a publisher with one or two analyzed shows cannot dominate share-based rankings.

## Identifying a publisher

The publisher-scoped endpoints (`/v1/podcasts/publishers/{id}/...`) accept the same publisher identifier as the rest of the [publisher endpoints](/podcasts/publishers): a slug (recommended — `iheartpodcasts`, `bbc-radio-4`, `bloomberg`) or the publisher ID.

## Publisher profile

The composite profile is the one-call summary an advertiser asks for first: "is this publisher's catalog broadly placeable?"

<CodeGroup>
  ```bash curl theme={"dark"}
  curl "https://api.particle.pro/v1/podcasts/publishers/bloomberg/suitability" \
    -H "X-API-Key: $PARTICLE_API_KEY"
  ```

  ```js JavaScript theme={"dark"}
  const res = await fetch(
    "https://api.particle.pro/v1/podcasts/publishers/bloomberg/suitability",
    { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
  );
  const profile = await res.json();
  ```

  ```python Python theme={"dark"}
  res = httpx.get(
      "https://api.particle.pro/v1/podcasts/publishers/bloomberg/suitability",
      headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
  )
  profile = res.json()
  ```
</CodeGroup>

The response carries the full picture in one round-trip:

* **`tier_breakdown`** — counts and shares of `SAFE`, `LIMITED`, `SENSITIVE`, `UNSAFE` across the publisher's analyzed catalog, plus a `placeable_share` (`SAFE` + `LIMITED`) — the "broadly buyable" slice.
* **`category_breakdown`** — one entry per GARM category, always 12 entries even when prevalence is `NONE`, with prevalence counts, advertiser-relevant treatment counts (`PROMOTIONAL`, `GLAMORIZING`), and a `high_risk_count` (FREQUENT/PERVASIVE or GLAMORIZING).
* **`top_concerns`** — up to three categories ranked by `high_risk_count`. Surfaced separately so callers can scan a publisher's worst dimensions without traversing the full breakdown.
* **`confidence_breakdown`** — `LOW` / `MEDIUM` / `HIGH` counts of the agent verdicts that produced this rollup.
* **`coverage.analyzed_coverage` + `coverage.quality`** — context for the composition above.

## Drill down to specific podcasts

When the profile shows concerning composition, drill into the specific shows. The drill-down endpoint returns a paginated list of the publisher's analyzed podcasts with their tier, confidence, and flagged categories.

```bash theme={"dark"}
# Most-risky shows in the iHeart catalog
curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/suitability/podcasts?sort=risk_desc&limit=10" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# iHeart shows where 'illegal_drugs_alcohol_tobacco' content is at least OCCASIONAL
curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/suitability/podcasts?category=illegal_drugs_alcohol_tobacco&min_prevalence=OCCASIONAL" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# iHeart shows that GLAMORIZE 'crime_harmful_acts' content
curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/suitability/podcasts?category=crime_harmful_acts&treatment=GLAMORIZING" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

Each entry surfaces only enough per-category context to make the row scan-able (`code`, `prevalence`, `treatment`, derived `risk_level`). Per-category reasoning and evidence excerpts are intentionally not surfaced here — fetch `GET /v1/podcasts/{id}/suitability` for full per-category detail on a specific show.

Sort options:

* **`risk_desc`** *(default)* — `UNSAFE` first, then `SENSITIVE`, `LIMITED`, `SAFE`.
* **`risk_asc`** — `SAFE` first.
* **`recently_evaluated`** — most-recent assessment first; useful when you want to surface shows whose verdicts were just refreshed.

## Cross-publisher leaderboard

Rank publishers against each other on one of four metrics:

| Metric           | Sorted by                                     |
| ---------------- | --------------------------------------------- |
| `safest`         | `SAFE` share of the analyzed catalog (desc)   |
| `riskiest`       | `UNSAFE` share of the analyzed catalog (desc) |
| `most_placeable` | combined `SAFE` + `LIMITED` share (desc)      |
| `most_analyzed`  | absolute `analyzed_podcasts` count (desc)     |

```bash theme={"dark"}
# Top 25 publishers with at least 5 analyzed shows, ranked safest first
curl "https://api.particle.pro/v1/podcasts/suitability/publishers/leaderboard?metric=safest&min_analyzed_podcasts=5&limit=25" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# Publishers most exposed to UNSAFE-tier shows
curl "https://api.particle.pro/v1/podcasts/suitability/publishers/leaderboard?metric=riskiest" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

<Note>The leaderboard reflects each publisher's *current* tier composition (sourced from the denormalized tier on each podcast). It does not accept a historical date window — paginate the audit history per show via `GET /v1/podcasts/{id}/suitability?include=history` if you need point-in-time analysis.</Note>

Each row carries the publisher's `tier_breakdown`, `coverage.analyzed_podcasts`, `coverage.analyzed_coverage` + `coverage.quality`, and `metric_value` (the actual sort key — a share \[0, 1] for `safest` / `riskiest` / `most_placeable`, an absolute count for `most_analyzed`).

## Category pivot — the regulated-brand view

The most differentiated view in this surface. For one of the 12 GARM categories, rank publishers by exposure across their catalog. An alcohol advertiser pivots on `illegal_drugs_alcohol_tobacco` and immediately sees which publishers carry the highest catalog-level exposure (and at what prevalence + treatment); a family brand pivots on `adult_sexual` or `hate_speech_aggression` to build an exclusion list.

```bash theme={"dark"}
# Publishers most exposed to illegal_drugs_alcohol_tobacco content
curl "https://api.particle.pro/v1/podcasts/suitability/categories/illegal_drugs_alcohol_tobacco/publishers" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# Same, but only count PROMOTIONAL exposures (sponsored CBD, alcohol endorsements)
curl "https://api.particle.pro/v1/podcasts/suitability/categories/illegal_drugs_alcohol_tobacco/publishers?treatment=PROMOTIONAL" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# Publishers where 'debated_social_issues' content is at least OCCASIONAL
curl "https://api.particle.pro/v1/podcasts/suitability/categories/debated_social_issues/publishers?min_prevalence=OCCASIONAL" \
  -H "X-API-Key: $PARTICLE_API_KEY"

# Reverse view — publishers *least* exposed to a category
curl "https://api.particle.pro/v1/podcasts/suitability/categories/adult_sexual/publishers?direction=least_exposed" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

Each row in the response surfaces:

* `exposure_share` — share of the publisher's analyzed catalog with any non-`NONE` prevalence in the category (or above `min_prevalence` when set, restricted to `treatment` when set).
* `high_risk_count` — FREQUENT/PERVASIVE or GLAMORIZING podcasts in the category.
* `prevalence_breakdown` and `treatment_breakdown` — the full distribution of exposures in this category across the publisher's catalog.
* `example_podcasts` — up to three example podcasts from the publisher's catalog that exhibit the highest exposure (ranked PERVASIVE → INCIDENTAL, GLAMORIZING → DOCUMENTARY, then by ID for determinism) so the abstract shares anchor to concrete shows you recognize.

## Tier classification recap

The publisher rollups use the same four-tier verdict as the per-podcast assessment:

| Tier        | Framework risk level | Advertiser fit                                                                       |
| ----------- | -------------------- | ------------------------------------------------------------------------------------ |
| `SAFE`      | Low Risk             | Suitable for all advertisers, including kid-directed and family brands.              |
| `LIMITED`   | Medium Risk          | Suitable for most advertisers; family brands may apply caution.                      |
| `SENSITIVE` | High Risk            | Many brands skip; suitable for general-audience and adult-product advertisers.       |
| `UNSAFE`    | Brand Safety Floor   | No monetization — content violates the Brand Safety Floor for at least one category. |

See the [per-podcast suitability docs](/podcasts/suitability) for the full GARM category set, the prevalence + treatment axes, and the risk-derivation rules.