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.
Return all Tornado Warnings for the Des Moines WFO in shapefile format during 2023.
Provide all Tornado Warnings valid at 2120 UTC on 21 May 2024
Same request, but return an excel file
Same request, but return csv
Same request, but using the more verbose parameterization for the timestamp and also filtering the result by text products signed by 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). |