National Alert Browser: browse active weather alerts by service/country (US, Canada, Europe)

[kellylford]

Summary

A new National Alert Browser for iOS that lets users browse active government weather alerts independent of any saved city — by service/country — with a scannable, VoiceOver-first digest. Reached from a new Weather Alerts section in the Browse tab, behind the alertBrowserEnabled feature flag (default on).

Branch: feature/alert-browser · shipped/tested on a physical iPhone throughout.

What it does

Top level — by service/country:

• United States — NWS (api.weather.gov)
• Canada — Environment Canada / ECCC (api.weather.gc.ca)
• Europe — MeteoAlarm, 36 member countries (feeds.meteoalarm.org), each row showing its live active-alert count

The digest (per region):

• Alerts are collapsed by event type so 25 county-level "Flood Warning" products read as one row, not 25.
• Grouped under severity section headers that carry counts ("Severe, 43 alerts").
• Two filters:
  • Severity buttons (Extreme / Severe / Moderate / All) — exclusive: each shows only that severity; only "All" is inclusive. Each segment announces its count in VoiceOver ("Extreme, 3 alerts, 1 of 4").
  • Type menu (hazard family) — Storms, Tropical, Flooding, Rain, Heat, Winter, Wind, Fire, Fog, Marine & Coastal, Air Quality, Other. Only families present right now are offered, each with a count. "Storms" gathers tornado/thunderstorm/severe-weather products that NWS otherwise scatters across three severities.
• Tapping a category → affected areas → the existing AlertDetailView.

Architecture: every provider normalizes into the existing WeatherAlert model, so AlertDetailView, severity coloring, and accessibility labels are reused unchanged. New AlertSource cases .eccc / .meteoalarm. No new dependencies.

Key learnings & decisions

• None of the alert sources cost anything. NWS, ECCC, and MeteoAlarm are all free, keyless public services. MeteoAlarm ≠ Open-Meteo — the alert browser makes zero Open-Meteo (paid) calls.
• NWS /alerts/active rejects a limit param (HTTP 400). It returns all active alerts without pagination. This was the first "Couldn't load alerts" bug.
• NWS severity tags are miscalibrated for browsing: Tornado Warning = Extreme, Severe Thunderstorm Warning = Severe, but the Watches are Moderate and Air Quality is "Unknown." We remap Air Quality → Moderate; the hazard-type filter exists precisely because severity alone doesn't group "storms."
• Small Craft Advisories are tagged Minor (not Moderate), so they only surface under "All" — which let us drop a separate land/marine toggle entirely; the severity buttons handle marine noise for free.
• Feed data quality varies by country. Austria supplies glued English event names ("Heatwarning", "Thunderstormwarning") — we de-glue before "warning". Some feeds emit a raw awareness_type=3, awareness_level=2 dump instead of an event name — we decode the structured awareness_type code into a real name ("Thunderstorm warning").
• The hazard classifier had to learn two vocabularies. A live sanity check across Canada + 18 European feeds showed 1,334 alerts (35%) landing in "Other" because Europe says "high-temperature" where the US says "heat," issues "rain" warnings, etc. After broadening the keywords and adding a Rain family, "Other" fell to 29 (0.7%) — the only remainder being Greece's genuinely unlabeled "Yellow Warning."
• Accessibility drove the UI. VoiceOver was reading a summary header as one long run-on string; counts were moved onto the severity headers and category rows, and the exclusive severity filter reads its counts per segment.

Design questions still open

• Default severity is "All" (nothing hidden on open) — reduce via buttons. Alternative would be a specific default, but that hides other severities.
• Type menu is a dropdown (11 families won't fit as segments) — could become a second scrollable button row if desired.
• Greece's generic "Yellow Warning" (~28 alerts) stays in "Other."
• Non-European sources beyond CA/US (Australia BOM, Japan JMA, NZ MetService) are candidates but need messier, separate integrations.
• VoiceOver walkthrough of every new screen on-device is still worth a dedicated pass before merge.

Testing

• Builds clean for simulator and device (Xcode 26.6).
• Verified live against all three feeds; cross-checked the digest against raw API counts (e.g. "1 Severe Thunderstorm Warning in the US" matched the feed exactly).
• Hazard classifier validated against live CA + EU data (numbers above).

[kellylford]

Shipped + learnings to retain

Delivered in PR #88, merged to main (ae2591a) at v1.5.8 build 2 — on the TestFlight track. Capturing the non-obvious things from development/review so they're not lost.

Data-source gotchas (per provider)

NWS (US)

• /alerts/active rejects a limit query param → HTTP 400. Don't add one.
• areaDesc format varies by product type: county-based warnings (Severe Thunderstorm Warning) already carry the state ("Mahoning, OH"); zone-based products (Special Weather Statement) are bare county/zone names with no state, and a single statement can span multiple states (real example: Limestone/Madison/Jackson = AL, Moore/Lincoln/Franklin = TN).
• The state is always recoverable from geocode.UGC — each code's first two letters are the state postal abbreviation (OHC099 → OH), and the UGC array is parallel to areaDesc. We now zip them and append ", <state>" where missing. Guardrails: leave already-suffixed names alone; skip marine-zone prefixes (ANZ, GMZ, LEZ, …) via a valid-state-abbreviation set so a coastal zone doesn't get ", AN".
• Air Quality Alerts come through with NWS severity "Unknown" → remapped to Moderate so they don't strand in an Unknown bucket.

MeteoAlarm (Europe)

• Some members emit dirty data: Austria glues event names ("Heatwarning"), and some feeds dump raw awareness_type=… strings or empty events. We repair via the structured awareness_type code → hazard name.
• Alerts may omit an identifier → derive a stable content-based id (slug + event + area + onset + expires), never the array index, or ForEach identity churns on refetch.

ECCC (Canada)

• Severity derived from risk_colour_en (red/orange/yellow/grey), falling back to alert type.

Design decisions worth remembering

• Every provider normalizes into the shared WeatherAlert model, so AlertDetailView + severity coloring + a11y are reused. New AlertSource cases .eccc / .meteoalarm.
• Two independent filters, AND-combined: severity (Extreme/Severe/Moderate/All, exclusive) × hazard type family. Severity=All + Type=Storms = every storm-family alert at every severity — a genuinely useful "active day" view.
• The "Storms" family is specific: tornado, thunderstorm (incl. severe), severe weather, special weather statement, lightning. Flooding / Tropical / Wind are deliberately separate families — so a storm's flash-flood and high-wind products land under Flooding/Wind, not Storms. This is intentional (keeps "Other" at ~0.7% across live CA+EU data). If we ever want Storms to pull convective flood/wind in, it's a one-line classifier change.
• Known judgment call: "Special Weather Statement" always classifies as Storms, but NWS also issues SPS for fog/wind. Correctly re-bucketing would need the description text; left as-is.

UX / behavior notes

• Pull-to-refresh keeps existing alerts on screen (no loading-row flash), and a transient refresh failure keeps the valid alerts rather than wiping to an error screen (safety). Caveat: a failed refresh is currently silent — pairs naturally with the "last updated" work (Show a "last updated" time throughout the app #90).
• Count caches: the Europe country-list counts are cached ~5 min (why a refresh there doesn't change them); the digest fetch itself is not cached — always fresh.
• Perf: ISO8601/DateFormatters are cached as static singletons (were allocated hundreds of times per US load); hazard classification is computed once per render.

Follow-ups opened

• Show a "last updated" time throughout the app #90 — "last updated" timestamp throughout the app (city list, browse state/country lists, alert view).
• Alert browser: improve area/region labeling for non-US sources (Canada, MeteoAlarm) #91 — improve area/region labeling for non-US sources (ECCC province, MeteoAlarm regions). The US UGC-prefix trick is US-specific and doesn't generalize.
• Alert browser: multi-select hazard types + saveable filter presets #92 — multi-select hazard types + saveable filter presets/favorites.

Still-open follow-ups from the PR

• Full VoiceOver walkthrough of every new screen (incl. verifying the new state suffixes read well, e.g. "Limestone, A-L").
• Greece's generic "Yellow Warning" stays in "Other."
• Possible additional sources: Australia BOM, Japan JMA, NZ MetService.

🤖 Generated with Claude Code