---
title: "Cumulative population exposure for a risk-zone product."
method: GET
path: "/v1/products/{product_id}/exposure-summary"
tags: ["Products"]
---

# Cumulative population exposure for a risk-zone product.

`GET /v1/products/{product_id}/exposure-summary`

## Request

- Base URL: `https://api.smarterweather.com`
- URL: `https://api.smarterweather.com/v1/products/{product_id}/exposure-summary`
- Auth: HTTP bearer

Returns the total population inside all risk-band polygons at or above
a threshold level for a risk-zone product's latest issuance — the data
behind headlines like "~57M under major heat risk".

Generic across every product that publishes exclusive risk-band
polygons (NWS HeatRisk today; SPC categorical, WPC flood, and
winter/cold outlooks later). Because the bands are spatially exclusive,
a cumulative `>= min_level` figure is a straight sum with no
double-counting.

### Parameters

`min_level` is the inclusive cumulative threshold on the ordinal
`risk_level` (e.g. HeatRisk `3` = Major and above). When omitted the
upstream default (`1`, any elevated risk) applies. `valid_time` selects
a specific issuance (RFC3339); omit it for the latest.

### Caching

Successful responses carry `Cache-Control: public, max-age=60,
stale-while-revalidate=60`. Edge cache key includes the query string
so each `min_level` / `valid_time` variant gets its own TTL.

### Auth

Standard sw-api Bearer auth applies.

## Path parameters

- `product_id` string, required

## Query parameters

- `min_level` integer
- `valid_time` string, date-time

## Response `200`

Cumulative population-exposure summary.

- object
  - `product_id` string, required
  - `min_level` integer, required
  - `population` integer, required: Total population under risk_level >= min_level.
  - `feature_count` integer, required: Number of risk-band polygons contributing to the sum.
  - `valid_time` string, date-time, nullable: Issuance the summary was computed for (null if no features).

## Other responses

- `400`: Bad request.
- `401`: Missing or invalid API key. Carries a `WWW-Authenticate` challenge and a `next_steps` extension. `recommended` is `device_flow`: the object is a complete no-install mint recipe.
- `403`: API key lacks the required scope. Carries a `WWW-Authenticate` challenge with `error="insufficient_scope"` and a `next_steps` extension.
- `429`: Rate limit exceeded. Carries a `next_steps` extension (`recommended: upgrade`, plus `pricing` and `usage`) telling the caller how to lift the limit.
- `500`: Internal server error.
- `502`: Bad gateway. The service received an invalid response from an upstream data source. Transient; clients should retry with backoff.
- `503`: Service unavailable. An upstream dependency is unavailable or shedding load (type `service-unavailable`). Transient; retry with backoff and honor any `Retry-After` header.
- `504`: Gateway timeout. An upstream data source did not respond within the service's budget.

---

[API](https://skmtc.dev/smarterweather/apis/smarter-weather-api.md) · [All operations](https://skmtc.dev/smarterweather/apis/smarter-weather-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smarterweather/apis/smarter-weather-api/revisions/520d55a696e4?raw)