Return to API Services or Download User Interface.

Documentation for /cgi-bin/request/gis/watchwarn.py

This service emits shapefiles (with additional csv included), or even Excel files. This service is rather blunt force and perhaps you should review the mountain of adhoc JSON/API services found at IEM Legacy JSON Services or at IEM API Services .

Changelog

  • 2025-07-12: Added fcster parameter to filter results by forecaster name (case-insensitive matching). This field is also added to the output.
  • 2025-05-09: Fixed issue with ETN DBF column allways being (null).
  • 2024-10-28: The service default for parameter simple was set back to yes. It was mistakenly set to no when this was migrated to pydantic.
  • 2024-10-28: Optimize the zipfile response by streaming the result.
  • 2024-10-22: Fix and better document the at parameter for when timeopt=2.
  • 2024-07-03: Added a accept=csv option to allow for CSV output.
  • 2024-06-26: Added limitpds parameter to limit the request to only include products that have a PDS (Particularly Dangerous Situation) tag or phrasing.
  • 2024-05-14: To mitigate against large requests that overwhelm the server, a limit of one year's worth of data is now in place for requests that do not limit the request by either state, phenomena, nor wfo.
  • 2024-05-09: Migrated to pydantic based CGI input validation.

Example Usage

Return all Areal Flood, Flash Flood, Severe Thunderstorm, and Tornado Watch and Warnings for the state of Mississippi during 2024. Note how the phenomena and significance parameters are repeated so that each combination is present.

https://mesonet.agron.iastate.edu/cgi-bin/request/gis/watchwarn.py?accept=shapefile&sts=2024-01-01T00:00Z&ets=2025-01-01T00:00Z&location_group=states&states=MS&limitps=yes&phenomena=FF,FA,SV,TO,FF,FA,SV,TO&significance=W,W,W,W,A,A,A,A

Return all Tornado Warnings for the Des Moines WFO in shapefile format during 2023.

https://mesonet.agron.iastate.edu/cgi-bin/request/gis/watchwarn.py?accept=shapefile&sts=2023-01-01T00:00Z&ets=2024-01-01T00:00Z&wfo[]=DMX&limitps=yes&phenomena=TO&significance=W

Provide all Tornado Warnings valid at 2120 UTC on 21 May 2024

https://mesonet.agron.iastate.edu/cgi-bin/request/gis/watchwarn.py?accept=shapefile&at=2024-05-21T21:20Z&timeopt=2&limitps=yes&phenomena=TO&significance=W

Same request, but return an excel file

https://mesonet.agron.iastate.edu/cgi-bin/request/gis/watchwarn.py?accept=excel&at=2024-05-21T21:20Z&timeopt=2&limitps=yes&phenomena=TO&significance=W

Same request, but return csv

https://mesonet.agron.iastate.edu/cgi-bin/request/gis/watchwarn.py?accept=csv&at=2024-05-21T21:20Z&timeopt=2&limitps=yes&phenomena=TO&significance=W

Same request, but using the more verbose parameterization for the timestamp and also filtering the result by text products signed by john

https://mesonet.agron.iastate.edu/cgi-bin/request/gis/watchwarn.py?accept=shapefile&year3=2024&month3=5&day3=21&hour3=21&minute3=20&timeopt=2&limitps=yes&phenomena=TO&significance=W&fcster=john

CGI Arguments

The following table lists the CGI arguments that are accepted by this service. A HTTP GET request is required. Fields of type Multi-Params or CSV value can accept either a comma separated list or multiple parameter and value combinations. For example, ?foo=1&foo=2 is equivalent to ?foo=1,2.

Field Type Description
accept string The format to return, either shapefile or excel.
at string The timestamp to use when timeopt=2, which the service provides events valid at the specified time.
addsvs string Include polygons that were included within any followup statements after issuance.
ets string The end timestamp in UTC. The format is ISO8601, e.g. 2010-06-01T00:00Z.
limit0 string If yes, only include Tornado, Severe Thunderstorm, Flash Flood, and Marine Warnings.
limit1 string If yes, only include Storm Based Warnings.
limit2 string If yes, only include Emergency Warnings.
limitpds boolean If yes, only include products that have a PDS (Particularly Dangerous Situation) tag or phrasing.
limitps string If yes, only include the specified phenomena and significance.
location_group string The location group to use, either wfo or states.
phenomena Multi-Params or CSV value The two character VTEC phenomena(s) to include. If you provide more than one value, the length must correspond and align with the significance parameter.
simple string If yes, use a simplified geometry for the UGC counties/zones.
significance Multi-Params or CSV value The one character VTEC significance to include, if you provide more than one value, the length must correspond and align with the phenomena parameter.
states Multi-Params or CSV value List of states to include data for.
sts string The start timestamp in UTC. The format is ISO8601, e.g. 2010-06-01T00:00Z.
timeopt integer The time option to use, either 1 or 2, default is 1, which uses the start and end timestamps to determine which events to include. Option 2 uses the at timestamp to determine which events to include.
wfo Multi-Params or CSV value List of WFOs to include data for.
wfos Multi-Params or CSV value Legacy parameter, update to use wfo.
year1 integer The start timestamp components in UTC, if you specify a sts parameter, these are ignored.
year2 integer The end timestamp components in UTC, if you specify a ets parameter, these are ignored.
year3 integer The at timestamp components in UTC. When timeopt is 2, this is used to find all events that were valid at this time.
month1 integer The start timestamp components in UTC, if you specify a sts parameter, these are ignored.
month2 integer The end timestamp components in UTC, if you specify a ets parameter, these are ignored.
month3 integer The at timestamp components in UTC. When timeopt is 2, this is used to find all events that were valid at this time.
day1 integer The start timestamp components in UTC, if you specify a sts parameter, these are ignored.
day2 integer The end timestamp components in UTC, if you specify a ets parameter, these are ignored.
day3 integer The at timestamp components in UTC. When timeopt is 2, this is used to find all events that were valid at this time.
hour1 integer The start timestamp components in UTC, if you specify a sts parameter, these are ignored.
hour2 integer The end timestamp components in UTC, if you specify a ets parameter, these are ignored.
hour3 integer The at timestamp components in UTC. When timeopt is 2, this is used to find all events that were valid at this time.
minute1 integer The start timestamp components in UTC, if you specify a sts parameter, these are ignored.
minute2 integer The end timestamp components in UTC, if you specify a ets parameter, these are ignored.
minute3 integer The at timestamp components in UTC. When timeopt is 2, this is used to find all events that were valid at this time.
fcster string Optional forecaster filter to limit results to events where the forecaster field matches this value (case-insensitive).