Weather alerts look simple on the surface — hit an endpoint, get back a list of active alerts, done. Then you ship to production and discover that “active alerts” is a surprisingly slippery concept, your users are seeing the same tornado watch five times, and you can’t tell whether a missing alert means there’s no alert or your polling interval just missed an update window.
Here’s what’s actually going on, and how to consume alert data in a way that doesn’t quietly fail.
What an Alert Object Actually Represents
A weather alert isn’t a point-in-time event. It’s a validity window — an active period with a defined start (effective) and end (expires), sometimes updated mid-flight by the issuing agency before the original expiry. NWS alerts, for example, can be updated, cancelled, or superseded without the original disappearing from all feeds simultaneously. The same physical storm system might have an active Watch, an overlapping Warning issued two hours later, and a Statement refreshing on a 30-minute cycle — all returned in the same API response for the same coordinate.
If your app just renders whatever comes back, the user gets three cards for one storm. That’s alert fatigue before anything dangerous has even happened.
Deduplication Isn’t Trivial
The naive approach is to deduplicate on alert headline text. Don’t. Headlines change between updates — an NWS product can update the wording, extend the expiry by an hour, and change a probability figure all in a single refresh, and now your deduplication key has broken and you’ve got a ghost duplicate alongside the real updated record.
The more robust approach is to key on alert type + event + issuing office + effective timestamp. If all four match, it’s the same logical alert even if the expiry or description text has changed. When you store it, overwrite the existing record rather than appending a new one.
In pseudocode:
alert_key = f"{alert.event}::{alert.headline[:40]}::{alert.effective}"
if alert_key not in seen_alerts:
seen_alerts[alert_key] = alert
notify_user(alert)
else:
seen_alerts[alert_key] = alert # Update in place, no re-notify
The headline[:40] slice is deliberate — enough to differentiate event types, not so much that minor text rewording creates a new key. Test this against your actual data before trusting it; headline formats differ between regions and issuing offices.
Polling Interval vs. Alert Lifecycle
This is where most implementations quietly get it wrong. Poll on a five-minute interval and an alert that’s issued and cancelled within three minutes — which happens during fast-moving convective events — will never appear. Your users needed that information and your app showed them nothing.
There’s no clean fix if you’re purely polling. The practical options are:
- Shorten the interval to one or two minutes for any location already flagged as “storm possible” in the forecast data — you have that context from the conditions endpoint.
- Accept the gap, document it, and don’t promise real-time alert delivery if you’re not building toward it deliberately.
- For genuinely time-critical use cases (outdoor event ops, field crews), ask whether a polling-based architecture is the right call at all versus a push-based model.
We don’t offer a push/webhook model for alerts currently — it’s on the roadmap — so if you’re building on WeatherAPI.com right now, you’re polling. Saying that plainly is more useful than implying a 60-second interval is “real-time.”
Caching Alerts Correctly
Alerts should not share a TTL with forecast data. A 15–30 minute forecast cache makes sense because forecast values drift slowly. A 15-minute alert cache means you might serve a tornado warning that was cancelled 14 minutes ago.
Two things to get right:
First, cache with a short TTL tied to the earliest expiry in the current alert set. If the soonest-expiring alert is four minutes out, cache for no longer than four minutes. When the cache busts, re-fetch. This maps directly to the real-world semantics of the data.
Second, distinguish between “no alerts returned” and “request failed.” If your API call errors and you serve a cached empty-alert response, you may be hiding an active event. Mark cached alert data with a fetched_at timestamp and surface a staleness indicator in your UI if the fetch age exceeds two polling cycles. Users handle “alerts may be delayed” better than they handle silently stale data.
Severity Ordering and What to Surface
When multiple alerts are active for a location, you need a severity hierarchy. NWS defines one: Extreme > Severe > Moderate > Minor > Unknown. Most alert API responses include a severity field that maps to this — but don’t assume it’s always populated or consistently spelled across different source agencies.
Build a fallback mapping based on the event field name itself. A “Tornado Warning” should rank above a “Wind Advisory” regardless of what the severity field says, because the event type carries the real information. A small lookup table covering the 20 or so most common event types is defensive coding that costs almost nothing and saves you from the UI edge case where a miscoded advisory renders above an active warning.
Geographic Scope: The Polygon vs. Point Problem
Weather alerts are issued for counties, forecast zones, or marine zones — not individual coordinates. When an API returns alerts for a lat/lon query, it’s doing a zone-lookup behind the scenes: which alert zones contain or overlap this point?
The practical implication: an alert for a large rural county might be technically “active” at a coordinate 80 kilometers from the area experiencing the actual hazard. A user in the far corner of a large county gets a tornado warning for a tornado touching down at the opposite end of that same county.
There’s no API-layer fix for this — it’s structural to how alert zones are defined, and the real solution requires polygon intersection against a finer-grained hazard footprint, which is significantly more involved. What you can do is include the alert area description in your UI rather than just the headline. “Tornado Warning — Polk County, Iowa” gives users more context than “Tornado Warning” alone and lets them make a more informed judgment about their own position.
One Pattern Worth Stealing
For a background job monitoring alerts across a set of locations — field operations, logistics fleet, outdoor event portfolio — the cleanest pattern we’ve found is a small state table:
CREATE TABLE active_alerts (
location_id VARCHAR(64),
alert_key VARCHAR(255),
event VARCHAR(128),
severity VARCHAR(32),
effective DATETIME,
expires DATETIME,
headline TEXT,
last_seen_at DATETIME,
notified_at DATETIME NULL,
PRIMARY KEY (location_id, alert_key)
);
On each poll cycle, upsert into this table. Anything where expires < NOW() gets purged. Anything where notified_at IS NULL triggers a notification. Updates to an existing alert key update the record but don’t re-trigger notification unless severity escalates — check that by comparing old vs. new severity on upsert.
Simple, auditable, and it degrades gracefully if your polling skips a cycle.
The Edge Case Nobody Mentions
DST transitions. If your alert timestamps are stored or displayed in local time without a timezone-aware parser, you will at some point show an alert expiry that’s an hour off — and during a severe weather event, an hour is not a rounding error. Parse all alert timestamps as UTC, store as UTC, convert to local only at display time. This applies to effective, expires, and any onset field.
Quick sanity check worth running: pick a location that recently had an alert, pull the raw API response, and confirm your parser is handling the timezone offset correctly. One test, run once, eliminates a whole category of future support questions.