Skip to content

Advisories

The active watches, warnings and advisories (the NWS set and any customer advisory sources your key can read) live on client.advisories. They need the read:observations scope; without it a call raises ForbiddenError.

from stormlore import Client

client = Client()
page = client.advisories.list("68102")    # every advisory covering ZIP 68102
page.to_dataframe()

Only the active set is served: there is no advisory history.

Where

The place is the first argument:

Place Means
"68102" every advisory covering any part of that ZIP code
["68102", "68104"] covering any of those ZIP codes
(41.26, -95.94) or a LatLon covering that point
nothing everywhere

A list of exactly two ZIP codes is two ZIP codes, never a point; coordinates written as text (("41.26", "-95.94")), a mix of ZIPs and coordinates, or text that is not a 5-digit ZIP raise ValueError before any request.

Then narrow with zone= (NWS zone codes, e.g. "NEZ052"), event= (event names; see types()) and source=. Each takes one value or a list, sent as repeated parameters. The API splits every value on commas, so a value containing a comma raises ValueError.

client.advisories.list((41.26, -95.94), event=["Winter Storm Warning", "Blizzard Warning"])
client.advisories.types("68102").to_dataframe()   # event, count

Shapes

Polygons come only when asked for:

page = client.advisories.list("68102", geometry=True)
page[0].geometry          # a GeoJSON mapping; None for an advisory defined by zones alone

Shapes are large: a page of the whole country with geometry can run to tens of MB. Filter by place first. The frame has a geometry column whenever it was asked for (even on an empty page), and only then.

Pages

The whole active set is normally 1–3 thousand advisories and fits in one default-sized page (5,000; limit= up to 10,000). count is the number on this page; next_offset is None on the last page, else pass it back as offset=:

for page in client.advisories.iter_list(event="Flood Warning"):
    page.to_dataframe()

iter_list asks for one page at a time, only as you advance it. The set is live, so an advisory can move between pages while you read them: one already yielded is dropped from later pages.

One advisory

detail = client.advisories.get(page[0].id, geometry=True)
detail.advisory.headline, detail.as_of

An id that is not active raises AdvisoryNotFoundError.

The frame

One row per advisory: id, event, severity, certainty, urgency, headline, area_desc, sent, effective, onset, expires, ends, source, provider, status, message_type, category, sender_name, description, instruction, ugc, zcta, zcta_status (times UTC; ugc and zcta stay lists), then geometry when asked for, then a customer source's values and attributes, named as for observations (values.<key> / attributes.<key> when a name is taken). An attribute that repeats a fixed column with the same value (a customer source's event, headline …, which the API already maps onto those columns) is dropped. frame.attrs["units"] names a customer value's units where the source gave them. Advisories are served as written: to_dataframe(units=...) raises.

Draw it

client.advisories.list("68102", geometry=True).plot()   # shapes, by severity

Every chart, drawn: charts and maps (pip install 'stormlore[viz]').