Alerts

Get a single NWS alert by id.

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.

get/v1/alerts/{id}

Request

  • Base URL: https://api.smarterweather.com
  • URL: https://api.smarterweather.com/v1/alerts/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Alert identifier: the id of an alert in alerts[] from GET /v1/alerts, or an alert's group_id or message_id. URL-encode embedded colons and slashes.

Query parameters

includestring

Comma-separated tokens. impact opts in to civic POI and building-count estimates (pois, buildings). Unknown tokens are ignored. Omitted on the default response so the lookup stays a primary-key read.

Response

Alert detail for the requested id.

group_idstring required

The alert's canonical id, stable across its updates (the NWS id of its first message).

message_idstring required

NWS-issued message identifier (matches Alert.id).

statusstring required

Alert lifecycle status (e.g., Actual, Exercise, Test).

eventstring required
severity'Extreme' | 'Severe' | 'Moderate' | 'Minor' | 'Unknown' required
urgency'Immediate' | 'Expected' | 'Future' | 'Past' | 'Unknown' required
certainty'Observed' | 'Likely' | 'Possible' | 'Unlikely' | 'Unknown' required
headlinestring required
descriptionstring

Multi-paragraph human-readable forecast / hazard description. Line endings vary by NWS office; clients should treat as opaque text.

instructionstring

Recommended actions (NWS-issued instruction text).

senderstring required

Issuing NWS office identifier.

effectivestring date-time required
expiresstring date-time required
onsetstring date-time required
endsstring date-time required
expirationstring date-time required

Final expiration time used for cache invalidation.

area_descstring

Human-readable affected area.

highlightsobject

Map of salient callouts extracted from the alert text (e.g., {"hazard": "Strong winds", "impact": "Loose debris possible"}).

geometryobject

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_latnumber double

Centroid latitude of the affected geometry.

centroid_lonnumber double

Centroid longitude of the affected geometry.

recommended_zoominteger

Suggested map zoom level when rendering the alert detail.

affected_populationinteger

Estimated population intersecting the alert geometry.

timezonestring

IANA timezone of the affected area (e.g., America/Chicago).

vtec_idstring

Upstream NWS VTEC identifier (when present). Useful for joining against external VTEC datasets; null for alerts without a VTEC code.

event_ending_timestring

Optional ending-time hint. Currently always omitted; clients should fall back to expires. Reserved for forward-compat.

Example response

{
  "group_id": "urn:oid:2.49.0.1.840.0.d1e1a911ed0a8ca7b56a9e6a3c5d6ba0035c88fb.001.1",
  "message_id": "urn:oid:2.49.0.1.840.0.d1e1a911ed0a8ca7b56a9e6a3c5d6ba0035c88fb.001.1",
  "event": "Severe Thunderstorm Warning"
}

Changes

No recorded changes to this operation across all 1 revision of this API.