Skip to content

NWS watch, warning, and advisory geometries

noaa:nws-warnings, available since v0.35.0, uses the Iowa Environmental Mesonet archive of National Weather Service products, at https://mesonet.agron.iastate.edu/cgi-bin/request/gis/watchwarn.py, checked on 2026-10-08. IEM is part of Iowa State University and is not an NWS endpoint; it is the maintained archive, because the official api.weather.gov/alerts keeps none.

Each fetched file is a zip holding a shapefile (.shp, .shx, .dbf, .prj, .cpg) and a CSV of the same attributes. One row is one VTEC event with one geometry, and the GTYPE column says which kind:

GTYPE Geometry From
P The storm-based warning polygon the forecaster drew 1 January 2002
C The outline of one county, parish, or forecast zone the product was issued for, named by NWS_UGC 1986 for tornado, severe thunderstorm, flash flood, and marine warnings; 12 November 2005 for the rest

A storm-based warning appears both ways: once as its polygon and once per county it was issued for. Watches, advisories, and zone-based warnings are C rows only. For one evening, 6 May 00Z to 7 May 12Z 2024, the archive holds 3,563 rows, among them 466 county rows of tornado watches (TO.A), 100 tornado warning polygons (TO.W, P) and the 224 counties they named, and heat, wind, fire, and flood products besides.

  • Both timestamps are required, in UTC, to the second. The window selects rows by ISSUED, inclusive at both ends. See what the window selects.
  • A window is fetched as one zip per UTC month it touches; nothing is requested while listing, and sizes are not known before download.
  • A place is a state: --location Oklahoma sends IEM's state filter. -p wfo=OUN,TSA names issuing offices instead. A county is refused, naming noaa:nws-vtec-events, which reads one county's events. A bbox or lat/lon is refused: the service filters by state or office, not by box.
  • -p events=TO.W,SV.W,TO.A narrows to VTEC phenomena and significance pairs.
  • -p storm_based=true keeps only the P rows.
  • -p followups=true adds the polygons of follow-up statements (SVS) issued after a warning, each its own row; by default only the issuance polygon is returned, with its impact tags.
  • variables is rejected: the columns are fixed. Free text is rejected as everywhere.
  • There is no bundled shapefile reader, so open() refuses the zip. geopandas.read_file(path) reads it directly, and so does pyshp's shapefile.Reader(path). The CSV inside needs nothing but pandas, and names the same columns in full, such as PRODUCT_ID for the DBF's PROD_ID. Timestamps are YYYYMMDDHHMM strings in UTC in the DBF and YYYY-MM-DD HH:MM in the CSV.
usdata fetch noaa:nws-warnings --start 2024-05-06T18:00Z --end 2024-05-07T12:00Z -p events=TO.W,TO.A
usdata fetch noaa:nws-warnings --location Oklahoma --start 2024-05-01 --end 2024-05-31 -p storm_based=true

What the window selects

IEM's documentation says the start and end "determine which events to include" without naming a column. Probing shows it is ISSUED, the event's start as last updated, and that the end is exclusive to the minute:

  • Every row of an unnarrowed request has ISSUED inside the window; 466 of the 3,563 rows above have INIT_ISS, the time of the product that started the event, before it. Those are mostly advisories and flood warnings sent the previous day to begin at a later hour.
  • [03:00, 03:27) UTC on 7 May returns 131 rows issued up to 03:26, and [03:00, 03:28) returns 136, adding the five issued at 03:27. The adapter sends the end plus one second, so a row issued at exactly the requested end minute is returned.
  • A Tornado Watch issued at 19:05 UTC on 6 May and running to 03:48 the next morning is not returned for a window inside it. The window asks what was issued, not what was in effect, as for noaa:nws-vtec-events.

For tornado and severe thunderstorm warnings ISSUED and INIT_ISS are the same instant. For a product that starts in the future they are not: IEM's FAQ gives a Winter Storm Watch sent at 17:00 UTC on 19 March 2019 to begin at 23:00 the next day, and recommends INIT_ISS as the time the public knew of it. A window meant to hold only what was known before some moment should therefore end at that moment and then filter on INIT_ISS locally.

The service also offers "events valid at" one instant (timeopt=2); the adapter does not expose it, since a usdata window is a span. Widen the window backwards and compare INIT_ISS and EXPIRED with the instant yourself.

Why the bytes are rewritten

The zip is built on request. Two identical requests seconds apart return different bytes: each member is stamped with the time the zip was built, and the DBF header with the date, while every member's content is otherwise identical. A lockfile could not pin such an answer, so the adapter writes a canonical zip: the same members in the same order, each stored uncompressed and stamped 1980-01-01 00:00 with no extra fields, and the DBF's last-update date set to 1980-01-01. Storing rather than deflating keeps the bytes the same whichever zlib a machine has; the file is four to five times the size of IEM's (1.8 MB zipped became 8.3 MB for the example evening). Every provenance sidecar records the rewrite under transformations (ADR 0053).

The archive itself changes too: rows are the latest state of each event, so an event still running when fetched can change later, and IEM has reprocessed the archive before, such as removing the polygons of cancelled segments on 10 April 2024. A restore that finds different rows fails its checksum rather than returning them silently.

Sizes and limits

Without a state or office the service caps a request at one year. The adapter asks for a UTC month at a time, so the cap is never reached. IEM's pregenerated yearly files give a sense of size: every product for 2024 is 335 MB zipped, the tornado, severe thunderstorm, marine, and flash flood warnings 45 MB, and their storm-based polygons 6.2 MB, and the canonical files written are four to five times those sizes. Narrow with events or storm_based for long windows.

Probes used to verify the endpoint and these behaviours:

U='https://mesonet.agron.iastate.edu/cgi-bin/request/gis/watchwarn.py'
curl -o a.zip "$U?accept=shapefile&sts=2024-05-06T00:00Z&ets=2024-05-07T12:00Z"   # 3,563 rows
curl "$U?accept=csv&sts=2024-05-07T03:00Z&ets=2024-05-07T03:27Z"                   # 131 rows, to 03:26
curl "$U?accept=csv&sts=2024-05-07T03:00Z&ets=2024-05-07T03:28Z"                   # 136 rows, to 03:27
curl "$U?accept=csv&sts=2024-05-07T03:00Z&ets=2024-05-07T03:30Z&limit1=1"          # 19 rows, all GTYPE P
curl "$U?accept=csv&sts=2024-05-07T03:00Z&ets=2024-05-07T03:30Z&addsvs=1"          # 163 rows, 46 P
curl "$U?accept=geojson&sts=2024-05-06T00:00Z&ets=2024-05-06T03:00Z"               # 422: no GeoJSON

IEM's JSON API has a GeoJSON service for warning polygons, /api/1/vtec/sbw_interval.geojson, but it holds storm-based polygons only: no watches, no advisories, and no county or zone rows. This dataset reads the shapefile service because it is the whole archive.

Metadata sources

Every value in the catalog entry's resolution, cadence, citation, terms, variables, and limits comes from one of these pages. A field the agency does not publish is left empty rather than estimated.

  • Coverage dates, the one-year download limit, and the pregenerated file sizes: IEM's download page.
  • Column meanings and units: the DBF schema in IEM's VTEC FAQ, which gives wind tags in MPH, hail tags in inches, and areas computed in an Albers projection.
  • Parameters: the service's own help page, at the endpoint with ?help.
  • Terms and license: IEM's disclaimer, which places its materials in the public domain and says attribution "would be appreciated". The citation names NWS as the origin and IEM as the archive.
  • Update frequency: IEM states none, and the entry says so; latency is empty for the same reason.
  • No window limit is declared: the adapter splits any window into months and enforces none.

NOAA access notes.

Reference

noaa:nws-warnings · Source only · Install from source to use this dataset. NWS Watch, Warning, and Advisory Geometries.

At a glance

  • Files: zipped shapefile and CSV (no reader)
  • Selection: Events starting inside an inclusive UTC window, one zip per UTC month; optionally one state or offices, event types, and polygon options
  • Required inputs: Both timestamps; optionally a state location or wfo, events such as TO.W, storm_based, and followups
  • Open locally: Local files; no bundled reader for this format
  • On usdata.dev: NWS watch, warning, and advisory polygons and areas, with a walkthrough

Parameters

Pass these as --param name=value to the CLI, as params: entries in a manifest, or as keyword arguments to build_query.

Parameter Meaning
events VTEC phenomena and significance pairs such as TO.W, SV.W, or TO.A; every watch, warning, and advisory by default.
followups Add the polygons of follow-up statements issued after a warning, each its own row; only the issuance polygon by default.
storm_based Keep only storm-based warning polygons (GTYPE P), dropping county and zone rows; false by default.
wfo Issuing office code(s) such as OUN or TSA, in place of a state location; every office by default.

Variables

Variable Units Meaning
WFO — Issuing office, the four-letter id without its leading K or P
ISSUED UTC, YYYYMMDDHHMM Event start as last updated; the window's field
EXPIRED UTC, YYYYMMDDHHMM Event end as last updated
INIT_ISS UTC, YYYYMMDDHHMM Time of the text product that started the event; never updated
INIT_EXP UTC, YYYYMMDDHHMM Event end as first issued; never updated
PHENOM — Two-letter VTEC phenomena, such as TO or SV
GTYPE — P for a storm-based polygon, C for a county, parish, or zone
SIG — One-letter VTEC significance, such as W warning, A watch, Y advisory
ETN — VTEC event tracking number
STATUS — VTEC status of the event's latest update, such as NEW, CON, CAN, EXP, UPG
NWS_UGC — UGC code of a county or zone row; empty on polygons
AREA_KM2 km2 Area IEM computed in an Albers projection
UPDATED UTC, YYYYMMDDHHMM When NWS last updated the event
HV_NWSLI — Hydrologic VTEC: forecast point's NWS location id
HV_SEV — Hydrologic VTEC: flood severity at issuance
HV_CAUSE — Hydrologic VTEC: cause of the flood
HV_REC — Hydrologic VTEC: whether a record crest was expected at issuance
EMERGENC — Whether IEM's unofficial logic marks the event an emergency at any point
POLY_BEG UTC, YYYYMMDDHHMM Polygon rows: when the polygon becomes valid
POLY_END UTC, YYYYMMDDHHMM Polygon rows: when the polygon expires
WINDTAG mph Polygon rows: impact-based wind gust tag
HAILTAG inches Polygon rows: impact-based hail size tag
TORNTAG — Polygon rows: impact-based tornado tag, such as RADAR INDICATED or OBSERVED
DAMAGTAG — Polygon rows: impact-based damage threat tag, such as CONSIDERABLE
PROD_ID — IEM id of the issuing text product
FCSTER — Product signature, often the forecaster
VTEC_YR — Year the event's tracking number belongs to

Catalog facts

  • Availability: Source only · intended for 0.35
  • Domain: Severe weather
  • Spatial resolution: A storm-based warning polygon, or one county, parish, or forecast zone outline, per row
  • Temporal resolution: Issue, expiry, and polygon times to the minute
  • Updates: Not stated by IEM, which processes the live NWS product stream; rows change as later products update an event
  • Terms of use: https://mesonet.agron.iastate.edu/disclaimer.php
  • Citation: National Weather Service watch, warning, and advisory products, as archived and served by the Iowa Environmental Mesonet of Iowa State University, accessed via usdata
  • Catalog date range: 1986-01-01 to open-ended
  • Coverage varies by station, product, and date; the range above does not guarantee observations.
  • Upstream documentation
  • License: Public domain (NWS products; IEM materials are public domain, attribution appreciated)
  • Transport: http
  • Adapter: usdata.providers.noaa.nws_warnings:NwsWarnings