---
title: "Active NWS hazard alerts"
method: GET
path: "/api/v1/weather/nws/alerts/active"
tags: ["Environment"]
---

# Active NWS hazard alerts

`GET /api/v1/weather/nws/alerts/active`

Return the set of NWS hazard alerts that are currently active (effective now, not yet expired). NWS issues ~500-1500 active alerts at any given moment across the United States and its territories: tornado warnings, flood warnings, heat advisories, coastal-flood watches, winter-storm warnings, marine warnings, and more. Zone-based alerts carry a null geometry and reference `affected_zones`; short-fuse convective warnings (Tornado, Severe Thunderstorm, Flash Flood, Special Marine) carry a polygon. All timestamps are ISO 8601 with the issuing office's local offset. Attribution: NOAA National Weather Service (api.weather.gov).

## Query parameters

- `area` string, nullable — Two-letter state or territory code (e.g. `NY`, `CA`, `PR`). Filters to alerts whose `affected_zones` lie within the area.
- `region_type` string, nullable — One of `land` or `marine`. Restricts to land-zone alerts or marine-zone alerts respectively.
- `zone` string, nullable — NWS zone ID to filter by (e.g. `NYZ071`). Returns alerts that list this zone in `affected_zones`.
- `event` string, nullable — Filter by event label (e.g. `Tornado Warning`, `Frost Advisory`). Use `/alert-types` to discover valid labels.
- `severity` string, nullable — Filter by severity: `Extreme`, `Severe`, `Moderate`, `Minor`, `Unknown`.
- `urgency` string, nullable — Filter by urgency: `Immediate`, `Expected`, `Future`, `Past`, `Unknown`.
- `certainty` string, nullable — Filter by certainty: `Observed`, `Likely`, `Possible`, `Unlikely`, `Unknown`.
- `limit` integer — Maximum number of alerts to return (NWS caps at 500).

## Response `200`

List of active NWS alerts with full CAP metadata.

- EnvelopeNwsAlertsPayload
  - `data` NwsAlertsPayload, required — Active-alerts list response.
    - `count` integer, required — Number of alerts returned.
    - `alerts` NwsAlert[], required — Active alert records.
      - `id` string, nullable — URN alert identifier.
      - `sent` string, nullable — Time the alert was sent by the originator (ISO 8601).
      - `effective` string, nullable — Time the alert becomes effective (ISO 8601).
      - `onset` string, nullable — Expected onset of the hazard (ISO 8601).
      - `expires` string, nullable — Time the alert expires (ISO 8601).
      - `ends` string, nullable — Expected end of the hazard (ISO 8601).
      - `status` string, nullable — Alert status: Actual, Exercise, System, Test, Draft.
      - `message_type` string, nullable — Message type: Alert, Update, Cancel, Ack, Error.
      - `category` string, nullable — CAP category (e.g. Met, Safety, Geo, Rescue).
      - `severity` string, nullable — Severity: Extreme, Severe, Moderate, Minor, Unknown.
      - `certainty` string, nullable — Certainty: Observed, Likely, Possible, Unlikely, Unknown.
      - `urgency` string, nullable — Urgency: Immediate, Expected, Future, Past, Unknown.
      - `response` string, nullable — Recommended response: Shelter, Evacuate, Prepare, Execute, Avoid, Monitor, Assess, AllClear, None.
      - `event` string, nullable — Event label (e.g. `Tornado Warning`, `Frost Advisory`).
      - `sender` string, nullable — Sender address of the originating WFO or office.
      - `sender_name` string, nullable — Human-readable name of the issuing office (e.g. `NWS Upton NY`).
      - `headline` string, nullable — Short alert headline.
      - `description` string, nullable — Full alert description text.
      - `instruction` string, nullable — Recommended actions for the public.
      - `area_description` string, nullable — Plain-language geographic area covered (e.g. `Southern Westchester; Northeast Suffolk`).
      - `affected_zones` string[] — List of NWS zone IDs covered by this alert (extracted from the affectedZones URL list).
      - `geocode` object — UGC + SAME codes identifying the alert area at the county/zone level.
      - `parameters` object — Upstream-specific CAP parameters (AWIPS identifier, WMO identifier, NWSheadline, VTEC, etc.).
      - `geometry` object, nullable — GeoJSON geometry when the alert is polygon-based (e.g. short-fuse convective warnings). Null for zone-based alerts.
    - `filters` object, required — Echo of the filter parameters supplied by the caller.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/d3e3d9c28132/schema)