Endpoint: threats

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.

Use our wizard to try out this endpoint

Supported Actions

The following actions are supported with the threats endpoint:

:id Requesting data by using the :id action is used for returning data for a particular item that has an ID associated with it. This is the primary method for requesting general weather information for a single location (observations, forecasts, advisories, etc.) as the location's name or a zip code serves as the id. Other endpoints may expect a certain value for the ID, such as storm cells whose ID value is a combination of the radar site identifier and unique identifier assigned to every storm cell. Refer to an endpoint's detailed documentation for specific information regarding how to use the :id action.

Supported Parameters

The following parameters are optional unless otherwise noted:

p p=:place Defines the location to query data for. Refer to the list of supported place value formats.
radius radius=:distance:unit When requesting the closest results within a circle, the radius determines how far from the specified location to search. A valid unit value must be included in your radius value, e.g., "5mi", "10km", "25miles". If no unit is provided, your value is assumed to be in meters by default.

Most endpoints utilize a default radius of 50 miles, though some endpoints, such as lightning, may have tighter restrictions specified.
fields fields=:string Provides a comma separated list of values for the API to return. This parameter is often used to limit the amount of data returned. See Reducing Output.

Examples

The /[:endpoint]/[:action]? portion within the query template below can be exchanged with any of the examples. Also, please note you will need to input your client credentials in the [ID] and [SECRET] fields which can be found under the Apps section of the members area.

https://api.aerisapi.com/[:endpoint]/[:action]?client_id=[ID]&client_secret=[SECRET]

Find the threats affecting Minneapolis, MN
/threats/minneapolis,mn?

Find the threats within a 200 mile radius that may affect zip code 55403 (Minneapolis, MN)
/threats/55403?radius=200miles&

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.

Default
GeoJSON

{
    "success": true,
    "error": null,
    "response": [{
        "loc": {
            "lat": 26.82339,
            "long": -80.13865
        },
        "place": {
            "name": "palm beach gardens",
            "state": "fl",
            "country": "us"
        },
        "profile": {
            "tz": "America\/New_York"
        },
        "periods": [{
            "timestamp": 1528311387,
            "dateTimeISO": "2018-06-06T14:56:27-04:00",
            "storms": {
                "phrase": {
                    "long": "An area of strong storms is approaching from the WSW with frequent lightning and up to 0.50 inch hail possible.",
                    "short": "An area of strong storms is approaching from the WSW with frequent lightning and up to 0.50\" hail possible."
                },
                "distance": {
                    "minKM": 10.3,
                    "minMI": 6.4,
                    "maxKM": 48.3,
                    "maxMI": 30,
                    "avgKM": 22.6,
                    "avgMI": 14
                },
                "direction": {
                    "toDEG": 61,
                    "to": "ENE",
                    "fromDEG": 241,
                    "from": "WSW"
                },
                "approaching": true,
                "speed": {
                    "minKTS": 14,
                    "minKPH": 25.9,
                    "minMPH": 16.1,
                    "maxKTS": 39,
                    "maxKPH": 72.2,
                    "maxMPH": 44.9,
                    "avgKTS": 21.4,
                    "avgKPH": 39.6,
                    "avgMPH": 24.6
                },
                "span": 133,
                "hail": {
                    "probSevere": 0,
                    "prob": 40,
                    "maxSizeIN": 0.5,
                    "maxSize": "<0.50",
                    "maxSizeCM": 1.27
                },
                "rotation": false,
                "tornadic": false,
                "advisories": null,
                "mda": {
                    "min": 3,
                    "max": 4,
                    "avg": 4
                },
                "dbz": {
                    "min": 46,
                    "max": 54,
                    "avg": 49.666666666667
                },
                "lightning": null
            }
        }]
    }]
}
								

{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [-80.13865, 26.82339]
        },
        "properties": {
            "loc": {
                "lat": 26.82339,
                "long": -80.13865
            },
            "place": {
                "name": "palm beach gardens",
                "state": "fl",
                "country": "us"
            },
            "profile": {
                "tz": "America\/New_York"
            },
            "periods": [{
                "timestamp": 1528311415,
                "dateTimeISO": "2018-06-06T14:56:55-04:00",
                "storms": {
                    "phrase": {
                        "long": "An area of strong storms is approaching from the WSW with frequent lightning and up to 0.50 inch hail possible.",
                        "short": "An area of strong storms is approaching from the WSW with frequent lightning and up to 0.50\" hail possible."
                    },
                    "distance": {
                        "minKM": 10.3,
                        "minMI": 6.4,
                        "maxKM": 48.3,
                        "maxMI": 30,
                        "avgKM": 22.6,
                        "avgMI": 14
                    },
                    "direction": {
                        "toDEG": 61,
                        "to": "ENE",
                        "fromDEG": 241,
                        "from": "WSW"
                    },
                    "approaching": true,
                    "speed": {
                        "minKTS": 14,
                        "minKPH": 25.9,
                        "minMPH": 16.1,
                        "maxKTS": 39,
                        "maxKPH": 72.2,
                        "maxMPH": 44.9,
                        "avgKTS": 21.4,
                        "avgKPH": 39.6,
                        "avgMPH": 24.6
                    },
                    "span": 133,
                    "hail": {
                        "probSevere": 0,
                        "prob": 40,
                        "maxSizeIN": 0.5,
                        "maxSize": "<0.50",
                        "maxSizeCM": 1.27
                    },
                    "rotation": false,
                    "tornadic": false,
                    "advisories": null,
                    "mda": {
                        "min": 3,
                        "max": 4,
                        "avg": 4
                    },
                    "dbz": {
                        "min": 46,
                        "max": 54,
                        "avg": 49.666666666667
                    },
                    "lightning": null
                }
            }]
        }
    }]
}
								

Response Properties

The following properties will be provided in every response object:

periods (array) Array of threat objects for current and potential forecast periods.
periods[#].timestamp (number) Unix timestamp of the time of the threats
periods[#].dateTimeISO (string) ISO 8601 valid date and time of the threats
periods[#].storms (object) The storms threat object. Null if no storm threats
periods[#].storms.phrase (object) Object of phrases for the storm threats
periods[#].storms.phrase.short (string) A shortened phrase of storm threats. Perfect for mobile phones where space is a limitation.
periods[#].storms.phrase.long (string) Longer phrase of storm threats. Perfect for medium size displays
periods[#].storms.phrase.full (string) Complete phrase of all storm threats, no direction abbreviations etc.
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
periods[#].storms.direction.to (string) The abbreviated direction from the specified location to the storm threats
periods[#].storms.direction.toDEG (number) The decimal direction from the specified location To the storm threats. Value from 0 - 360, with 0/360 = North
periods[#].storms.direction.from (string) The abbreviated direction the threats approaching from.
periods[#].storms.direction.fromDEG (number) The abbreviated direction the threats approaching from. Value from 0 - 360, with 0/360 = North
periods[#].storms.approaching (boolean) True if the storms are approaching, False is passing through.
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.speed (object) Object of the speed information of the storm threats
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.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.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.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 / very large hail
periods[#].storms.hail.maxSize (string) The maximum estimated hail size within the storm threats
periods[#].storms.hail.maxSizeMM (number) The maximum estimated hail size within the storm threats in millimeters
periods[#].storms.hail.maxSizeIN (number) The maximum estimated hail size within the storm threats in inches
periods[#].storms.tornadic (boolean) True if the approaching storm threats may be tornadic, false otherwise.
periods[#].storms.rotation (boolean) True if the approaching storm threats include a decent amount of mesoscale rotation, 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 value
periods[#].storms.mda.max (number) The maximum value
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 reported dbz within the storm threats
periods[#].storms.dbz.max (number) The maximum reported dbz within the storm threats
periods[#].storms.dbz.avg (number) The average reported dbz within the storm threats
loc.long (number) The longitude coordinate of the record.
loc.lat (number) The latitude coordinate of the record.
place.name (string) The place or nearest place to the record.
place.state (string) The state abbreviation in which the record is located. This may be null depending on the country.
place.country (string) The country abbreviation in which the record is located.
profile.tz (string) The timezone name association with the record's location.

Last modified: August 18, 2022