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]').