Threats

URL Path

https://data.api.xweather.com/threats/

Data Coverage

US, Puerto Rico, Guam

Update Interval

Near Real Time

Time Range

Latest

The threats endpoint provides a localized threat summary for the location provided. Currently, threats are limited to storm-based threats. The threats coverage area includes the 50 US states, in addition to Puerto Rico and Guam.

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.

periods.#.storms.hail (object)

Object of hail information for the approaching storm threats. Null if 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.

periods.#.storms.tornadic (boolean)

True if the approaching storm threats may be tornadic, false otherwise.

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.

periods.#.storms.mda (object)

Object of mesoscale rotation information for the storm threats. Null if 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.

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": ""
          }
        }
      }
    ]
  }
]

Endpoints