Alerts

Overview

The alerts endpoints return the watches, warnings, advisories and statements the National Weather Service has in effect for a point, a saved location or an area. The NWS feed is read every 60 seconds, so a new alert is normally available within two minutes of issue.

Storm-based warnings match by the polygon NWS drew. Zone-based alerts, such as winter storm, heat and wind products, match by the NWS public, county or fire zones they were issued for. Updates replace the message they reference and cancellations end it, so a response only ever holds what is currently in effect.

The point lookup is also available inside a forecast: /forecast/point/?include=nws_alerts adds the same count, alerts and metadata to the forecast response.

Typical uses

Showing official alerts next to a FLASH Edge forecast, newsroom and broadcast alerting, and operations dashboards that need to know when a site falls inside a warning.

Live stream

Alerts can also be pushed over a WebSocket at wss://api.flashweather.ai/ws/v1/stream/ as soon as the NWS feed is read, instead of polling. Authenticate with ?token= (dashboard token) or a secret API key in the X-Flash-API-Key header. Server-to-server clients must also send an Origin header for an allowed FLASH host. Access follows the same product as the REST endpoints.

Subscribe by saved location, by point, or to all saved locations. A new subscribe replaces the previous one, at most one every 5 seconds per socket (RATE_LIMITED otherwise). filters takes the same event, severity, urgency, certainty, status and message_type values as the query parameters. When you leave out message_type, its default (Alert,Update) applies to created and updated events only, so cancelled and ended events for your locations always reach you. The status default (Actual) and values you set yourself apply to every event.

{"action": "subscribe", "topics": ["alerts.nws"],
 "location_ids": [12], "points": [{"lat": 27.95, "lon": -82.46}],
 "filters": {"severity": "Extreme,Severe"}}

Each change to an alert that covers a subscribed location arrives as an event frame. event is one of nws_alert.created, nws_alert.updated, nws_alert.cancelled or nws_alert.ended, locations lists the subscribed locations inside the alert, and payload has the same shape as an item in the REST alerts list. A Cancel message ends the alert it refers to and is never active itself; it arrives as nws_alert.cancelled, and the alert it ends as nws_alert.ended.

Zone-based alerts go out as soon as they are read, matched against the zone shapes known at that moment. If NWS names a zone whose shape is still being fetched, nws_alert.updated follows for the same alert once the area is complete, usually within a minute, and may be the first event a location inside that zone receives. Events always arrive in id order.

{"type": "event", "id": "1759871230000-0", "topic": "alerts.nws", "event": "nws_alert.created",
 "ts": "2026-10-07T21:07:10Z", "schema_version": 1,
 "locations": [{"lat": 27.95, "lon": -82.46}], "payload": {"id": "urn:oid:...", "event": "Tornado Warning"}}

Keep the last id you received. After a reconnect, send it as last_event_id in the subscribe frame to receive what you missed (about the last 24 hours), followed by a replay_complete frame. complete: false there means some events were older than the replay window, so refresh with the REST endpoint.

Other frames: welcome, subscribed, heartbeat (every 25 seconds when idle), pong (reply to {"action": "ping"}) and error, which carries code, error and, where useful, details. Access is checked again about once a minute while the socket is open, so a revoked key, a logged out or expired token, or a lapsed product closes it. Close codes: 4001 not authenticated, 4003 product not included, 4008 the socket fell behind and 1011 delivery was interrupted (for both, reconnect with last_event_id), 4503 stream disabled.

Operations