Hazards

weather.hazards reads the official United States hazard record: CAP alerts and warning bulletins, National Hurricane Center storm data, river gauges and streamflow, and wildfire incidents with satellite fire detections. Every verb returns typed rows with an explicit source tag, and every row can be captured with its retrieval time so you can later reconstruct exactly what was knowable when.

What it covers

| Area | Verbs | Providers | |---|---|---| | Alerts and bulletins | alerts, text_products, post_storm_reports, issuing_offices | NWS live, Iowa State archive | | Tropical cyclones | tropical_cyclones, best_track, best_track_revisions | NHC live, HURDAT2 | | Flood and water | gauges, stage_and_flow, rating_curve, water_observations | NWS NWPS, USGS | | Wildfire | wildfires, hotspots | WFIGS, CAL FIRE, NASA FIRMS | | Point-in-time replay | capture_history, persist_rows, persist= on every read verb | local parquet (Python only) |

Every route is a United States government work or an open-data mirror of one. You can cache, persist, train on, and redistribute what these verbs return. The FIRMS routes ask for an acknowledgment of NASA FIRMS as the data source; the SDK reference carries the exact text.

Python

from mostlyright.weather import hazards

# Alerts in force for a UGC zone right now
active = hazards.alerts(zone="FLC086", active=True)
print(active[["event", "onset_at_utc", "expires_at_utc", "source"]])

# Active storms; off-season this returns 0 rows and does not raise
storms = hazards.tropical_cyclones()

# Wildfire incidents captured with retrieval time, replayable later
fires = hazards.wildfires(persist=True)
print(fires.attrs["source"])  # wfigs.current.live

Address resolution reads the manifest catalog, which requires MOSTLYRIGHT_API_KEY. The hazard data itself never consumes the key: the providers are keyless public routes, and the one optional credential in the adapter is your own free NASA key for the FIRMS bounding-box route (MOSTLYRIGHT_FIRMS_MAP_KEY).

Empty result or error

The verbs keep a strict line between “nothing happened” and “something is wrong”:

• An enumeration that asked a well-formed question and got a well-formed “nothing” returns an empty table with all columns and the source tag intact. A quiet zone, an off-season storm list, and a bulletin window with no filings all behave this way.
• Asking for a named thing that does not exist raises.
• Asking for a window the selected provider does not keep raises, and the error names the source= value that does keep it.
• A network or parse failure always raises. No verb returns None or drops rows silently.

Choosing a provider

Verbs that have both a live leg and an archive leg take source=. Leaving it unset picks the leg that covers your window; setting it pins one leg and makes the choice visible in every row’s source column. wildfires(source="calfire") selects the State of California feed instead of the federal interagency record.

Point-in-time capture

persist=True on any read verb writes the returned rows to a local parquet ledger keyed by capture time, and capture_history() reads them back exactly as they were retrieved. Incident records and forecasts get revised upstream; the ledger is how research on “what was published at the time” stays honest. This capture layer is Python only, because the store is parquet on disk.

TypeScript

The same verbs ship in @mostlyrightmd/weather on the hazards subpath and return the same snake_case rows inside the usual DataResult envelope:

import { alerts, gauges } from "@mostlyrightmd/weather/hazards";

const active = await alerts({ zone: "FLC086", active: true, apiKey });
const miami = await gauges({ bbox: [-80.5, 25.5, -80.0, 26.0], apiKey });

Most routes answer browser requests directly: alerts, bulletins, flood gauges, USGS water data, and the interagency wildfire feed all publish open CORS headers. The NHC hurricane routes, the CAL FIRE leg, and both FIRMS hotspot routes do not, so those verbs run in Node only; each verb’s reference page carries the measured verdict. There is no persist option in TypeScript.

Where to go deeper

The full adapter reference documents every verb’s parameters, the ten row schemas and their source tags, revision semantics for best tracks, flood threshold fields, and the wildfire licensing details: see the Python reference and TypeScript reference function pages, and the changelog for when each tier shipped.