--- title: "Get a single NWS alert by id." method: GET path: "/v1/alerts/{id}" tags: ["Alerts"] --- # Get a single NWS alert by id. `GET /v1/alerts/{id}` ## Request - Base URL: `https://api.smarterweather.com` - URL: `https://api.smarterweather.com/v1/alerts/{id}` - Auth: HTTP bearer Returns the full alert detail (geometry, spatial metadata, affected population, etc.) for a single NWS alert. Use the `id` of an alert in `alerts[]` from `GET /v1/alerts`. Accepts either a `group_id` (the alert's canonical id, stable across its updates) or a `message_id` (one NWS message in that alert); callers do not need to disambiguate. ### Caching A successful response carries `Cache-Control: max-age=60`, so an updated or cancelled alert can be served from a cache for up to 60 seconds. Partner keys get `private, max-age=60`: your own client may reuse the response for the full `max-age`, but shared caches (CDNs, proxies) must not store it, since each request on a partner key is metered and rate-limited individually. ### Geometry `geometry` is a GeoJSON object embedded in the response. Clients should treat it as opaque GeoJSON: forward-compat fields the upstream pipeline adds without a sw-api release pass through unchanged. ### Auth Standard sw-api Bearer auth applies. ## Path parameters - `id` string, required ## Query parameters - `include` string ## Response `200` Alert detail for the requested id. - AlertDetail: Full alert representation returned by `GET /v1/alerts/{id}`. Supersets `Alert` with full description, instruction, geometry, spatial metadata (centroid, recommended zoom, affected population), the upstream NWS VTEC identifier, and path-impact (`pois`, `buildings`) when it was computed. - `group_id` string, required: The alert's canonical id, stable across its updates (the NWS id of its first message). - `message_id` string, required: NWS-issued message identifier (matches `Alert.id`). - `status` string, required: Alert lifecycle status (e.g., `Actual`, `Exercise`, `Test`). - `event` string, required - `severity` 'Extreme' | 'Severe' | 'Moderate' | 'Minor' | 'Unknown', required - `urgency` 'Immediate' | 'Expected' | 'Future' | 'Past' | 'Unknown', required - `certainty` 'Observed' | 'Likely' | 'Possible' | 'Unlikely' | 'Unknown', required - `headline` string, required - `description` string: Multi-paragraph human-readable forecast / hazard description. Line endings vary by NWS office; clients should treat as opaque text. - `instruction` string: Recommended actions (NWS-issued instruction text). - `sender` string, required: Issuing NWS office identifier. - `effective` string, date-time, required - `expires` string, date-time, required - `onset` string, date-time, required - `ends` string, date-time, required - `expiration` string, date-time, required: Final expiration time used for cache invalidation. - `area_desc` string: Human-readable affected area. - `highlights` object: Map of salient callouts extracted from the alert text (e.g., `{"hazard": "Strong winds", "impact": "Loose debris possible"}`). - `geometry` object: GeoJSON geometry (Polygon / MultiPolygon) for the affected area when stored upstream. Treat as opaque GeoJSON; forward-compat fields the pipeline adds without a sw-api release pass through unchanged. - `centroid_lat` number, double: Centroid latitude of the affected geometry. - `centroid_lon` number, double: Centroid longitude of the affected geometry. - `recommended_zoom` integer: Suggested map zoom level when rendering the alert detail. - `affected_population` integer: Estimated population intersecting the alert geometry. - `timezone` string: IANA timezone of the affected area (e.g., `America/Chicago`). - `vtec_id` string: Upstream NWS VTEC identifier (when present). Useful for joining against external VTEC datasets; `null` for alerts without a VTEC code. - `event_ending_time` string: Optional ending-time hint. Currently always omitted; clients should fall back to `expires`. Reserved for forward-compat. - `pois` object: Civic POIs inside the alert polygon, computed once when the alert is written and stored on the alert. Present only when the request includes `include=impact`. `features` are capped at 50. Omitted when unavailable (null geometry, timeout, or estimate error) or when impact was not requested. Empty `counts`/`features` means computed zero, not unknown. - `counts` object - `features` object[] - `id` string - `name` string - `class` string - `buildings` object: ACS housing units and Overture building-class counts inside the alert polygon, computed once when the alert is written and stored on the alert. Present only when the request includes `include=impact`. `housing_unit` is ACS B25001, not residences. Class keys (`residential`, `commercial`, `industrial`, `civic`, `other`) appear only when building-class data is available. `features` is currently always empty. Omitted when unavailable (no housing data, timeout, or estimate error) or when impact was not requested. `counts.housing_unit: 0` is computed zero, not unknown. - `counts` object - `housing_unit` integer - `residential` integer - `commercial` integer - `industrial` integer - `civic` integer - `other` integer - `features` object[] ## 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. - `402`: Trial key free value ended (lifetime cap spent or key clock expired) while the claim window is still open. Carries `next_steps.recommended = claim` and the per-key claim href. - `403`: API key lacks the required scope. Carries a `WWW-Authenticate` challenge with `error="insufficient_scope"` and a `next_steps` extension. - `404`: Resource not found: a location that cannot be resolved (unknown ZIP, unrecognised free-text location), no upstream data for the location, or a missing resource. On a route that checks coverage (its description says so), a location outside the 50 US states and DC returns type `https://smarterweather.com/errors/outside-coverage`; that and the location-not-found problem carry `next_steps` (`recommended = coverage`). - `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)