Threats
https://data.api.xweather.com/threats/The global threats endpoint provides real-time localized summaries of storm-based threats, integrating storm cells, radar data, lightning strikes, and lightning threats. The endpoint uses NEXRAD-derived storm cell information, radar data, and lightning strikes to track cell movement, intensity, and severe weather signatures like hail and rotation within the US and its territories. It relies on lightning threats, strikes, and radar data outside the US. Additionally, the endpoint incorporates alerts such as tornado watches and warnings and severe thunderstorm watches and warnings globally to provide active threats currently affecting or may soon affect the location.
Requests
Every request to the endpoint must include one of the supported actions in the url.
https://data.api.xweather.com/threats/{action}?client_id={client_id}&client_secret={client_secret}&{params}Supported Actions
The following actions are supported with the /threats endpoint:
| Action | Description |
|---|---|
| :id | Type: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more. |
Response
The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.
Properties
loc (object)
The location of the record.
loc.lat (number)
The latitude coordinate of the record.
loc.long (number)
The place or nearest place to the record.
place (object)
Object containing information about the place or nearest place to the record.
place.name (string)
The place or nearest place to the record.
place.state (string)
The state abbreviation in which the response is located. This may be null or an empty string depending on the country.
place.country (string)
The 2 letter ISO-3166 country abbreviation in which the response is located.
profile (object)
Object containing information about the location or event.
profile.tz (string)
Timezone name of the location, such as America/New_York.
periods (array)
Array of threat periods.
periods.#.timestamp (number)
Unix timestamp of the time of the threats.
periods.#.dateTimeISO (string)
The date and time of the threats in ISO-8601 format.
periods.#.storms (object)
Object containing information about the storm threats.
periods.#.storms.phrase (object)
Object of phrases for the storm threats.
periods.#.storms.phrase.long (string)
Longer phrase of storm threats. Perfect for medium size displays
periods.#.storms.phrase.short (string)
A shortened phrase of storm threats. Perfect for mobile phones where space is a limitation.
periods.#.storms.distance (object)
Object of distance information of the threats from the specified location.
periods.#.storms.distance.minKM (number)
The minimum distance, in kilometers, of the group of storm threats from the specified location.
periods.#.storms.distance.minMI (number)
The minimum distance, in miles, of the group of storm threats from the specified location.
periods.#.storms.distance.maxKM (number)
The maximum distance, in kilometers, of the group of storm threats from the specified location.
periods.#.storms.distance.maxMI (number)
The maximum distance, in miles, of the group of storm threats from the specified location.
periods.#.storms.distance.avgKM (number)
The average distance, in kilometers, of the group of storm threats from the specified location.
periods.#.storms.distance.avgMI (number)
The average distance, in miles, of the group of storm threats from the specified location.
periods.#.storms.direction (object)
Object of the direction information of the threats from the requested location.
periods.#.storms.direction.toDEG (number)
The direction, in degrees, of the group of storm threats from the specified location. 0-359, where 0 is North.
periods.#.storms.direction.to (string)
The abbreviated direction from the specified location to the storm threats. N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW.
periods.#.storms.direction.fromDEG (number)
The direction, in degrees, the threats approaching from. 0-359, where 0 is North.
periods.#.storms.direction.from (string)
The abbreviated direction the threats are approaching from. N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW.
periods.#.storms.approaching (boolean)
True if the storms are approaching, False is passing through.
periods.#.storms.speed (object)
Object of the speed information of the threats from the requested location.
periods.#.storms.speed.minKTS (number)
The minimum speed of the group of storms threats in knots
periods.#.storms.speed.minKPH (number)
The minimum speed of the group of storms threats in kilometers per hour
periods.#.storms.speed.minMPH (number)
The minimum speed of the group of storms threats in miles per hour
periods.#.storms.speed.minMPS (number)
The minimum speed of the group of storms threats in meters per second
periods.#.storms.speed.maxKTS (number)
The maximum speed of the group of storms threats in knots
periods.#.storms.speed.maxKPH (number)
The maximum speed of the group of storms threats in kilometers per hour
periods.#.storms.speed.maxMPH (number)
The maximum speed of the group of storms threats in miles per hour
periods.#.storms.speed.maxMPS (number)
The maximum speed of the group of storms threats in meters per second
periods.#.storms.speed.avgKTS (number)
The average speed of the group of storms threats in knots
periods.#.storms.speed.avgKPH (number)
The average speed of the group of storms threats in kilometers per hour
periods.#.storms.speed.avgMPH (number)
The average speed of the group of storms threats in miles per hour
periods.#.storms.speed.avgMPS (number)
The average speed of the group of storms threats in meters per second
periods.#.storms.span (number)
An arc span angle of the storm threats affecting a location. If a storm threat is approaching from the WSW at 256 degrees. If Span = 75, then an arc can be drawn that is 75 degrees and is centered on the 256 degree direction (WSW) to show the area the storms are approaching from. Value will be 0 if outside of US.
periods.#.storms.hail (object)
Object of hail information for the approaching storm threats. Null if in non-US location or no hail within the storm threats.
periods.#.storms.hail.prob (number)
The probability (0-100) that the storm threats include hail.
periods.#.storms.hail.probSevere (number)
The probability (0-100) that the storm threats include severe hail. Severe hail is defined as 1 inch or larger.
periods.#.storms.hail.maxSizeIN (number)
The average hail size, in inches, of the storm threats.
periods.#.storms.hail.maxSizeMM (number)
The average hail size, in millimeters, of the storm threats.
periods.#.storms.rotation (boolean)
True if the approaching storm threats include a decent amount of mesoscale rotation, false otherwise. Value will be false if outside of US.
periods.#.storms.tornadic (boolean)
True if the approaching storm threats may be tornadic. Value will be false if outside of the US.
periods.#.storms.advisories (array)
An array of active severe storm related NOAA advisory VTEC codes.
If the location is under a severe thunderstorm warnings the value of ['SV.W']. If under both a Severe thunderstorm warning and Tornado warning the value may be ['TO.W', 'SV.W']. Refer to the advisories endpoint for more information on the advisory VTEC codes.
Null if no severe related storm advisories or outside the US.
periods.#.storms.mda (object)
Object of mesoscale rotation information for the storm threats. Null if outside of the US or no appreciable MDA for the approaching storms.
periods.#.storms.mda.min (number)
The minimum mesoscale rotation value of the storm threats.
periods.#.storms.mda.max (number)
The maximum mesoscale rotation value of the storm threats.
periods.#.storms.dbz (object)
Object of radar intensity of the approaching storms. Often used for determining the intensity of the precipitation.
Null if no dbz data available for the storm threats. For locations outside of the US, dbz is calculated based on precip rate.
periods.#.storms.dbz.min (number)
The minimum dbz value of the storm threats.
periods.#.storms.dbz.max (number)
The maximum dbz value of the storm threats.
periods.#.storms.dbz.avg (number)
The average dbz value of the storm threats.
periods.#.storms.lightning (object)
Object of lightning information for the approaching storms. Null if no lightning within the storm threats.
periods.#.storms.lightning.nearby (number)
The number of lightning strikes within 10 miles of the location.
periods.#.storms.lightning.approaching (number)
The number of lightning strikes within the group of storms that are approaching the location.
periods.#.storms.lightning.phrase (string)
The phrase describing the lightning threat. "Frequent Lightning", etc.
[
{
"loc": {
"lat": 34.8451,
"long": -95.55748
},
"place": {
"name": "hartshorne",
"state": "ok",
"country": "us"
},
"profile": {
"tz": "America/Chicago"
},
"periods": [
{
"timestamp": 1702657776,
"dateTimeISO": "2023-12-15T10:29:36-06:00",
"storms": {
"phrase": {
"long": "An area of heavy precipitation is approaching from the WNW.",
"short": "An area of heavy precipitation is approaching from the WNW."
},
"distance": {
"minKM": 4.4,
"minMI": 2.7,
"maxKM": 56.2,
"maxMI": 34.9,
"avgKM": 35.7,
"avgMI": 22.2
},
"direction": {
"toDEG": 103,
"to": "ESE",
"fromDEG": 283,
"from": "WNW"
},
"approaching": true,
"speed": {
"minKTS": 12,
"minKPH": 22.2,
"minMPH": 13.8,
"minMPS": 6.2,
"maxKTS": 25,
"maxKPH": 46.3,
"maxMPH": 28.8,
"maxMPS": 12.9,
"avgKTS": 18.5,
"avgKPH": 34.3,
"avgMPH": 21.3,
"avgMPS": 9.5
},
"span": 163,
"hail": null,
"rotation": false,
"tornadic": false,
"advisories": null,
"mda": null,
"dbz": {
"min": 42,
"max": 47,
"avg": 44
},
"lightning": {
"nearby": 0,
"approaching": 0,
"phrase": ""
}
}
}
]
}
]