Endpoint: stormcells

The storm cells dataset provides observed and forecast data for all storm cells across the United States. This is a NEXRAD-derived product that attempts to identify and track storm cell movement, along with reporting cell intensity and certain severe weather signatures within the cell, like rotation and hail. The forecast track can be used to determine when and where a cell will affect a particular location or area.

Use our wizard to try out this endpoint

Supported Actions

The following actions are supported with the stormcells 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.
closest The closest action will query the API for data that is closest to the requested place and return the results, if any, in order from closest to farthest. If no limit is provided in the request, then only the closest single result will be returned.

If your request does not return results, you may try setting or increasing the radius being used.
within The within action allows for returning data within a variety of different geometrical regions. Currently supported geometries include a circle (requires a center point and radius), rectangle (requires two coordinate points defining the top-left and bottom-right corners) and polygon (requires at least three coordinate points). Unlike the closest action, the results will not be returned in any particular order based on distance.
search The search action is used as a more general query method and expects the query to be defined with the custom query for the request. Unlike the closest action, results will not be returned in any particular order.
affects The affects action requests all places affected by a particular type of event, such as earthquake or storm cell. The query for places affected is unique for each endpoint it belongs to and can be a polygon (e.g., storm cell forecasts or warnings) or a circle with the center being the location of the event (e.g., earthquakes or fires). Instead of returning an array of objects specific to the endpoint, the affects action will always return an array of place objects in the same format as the within action on the places endpoint.

Note: Not all endpoints support this action, so refer to each endpoint's complete documentation to determine if supported and its usage.

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.
limit limit=:total The total number of results to return as an integer. Each endpoint may have a set maximum for this value depending on usage.

The default limit is 1 if not specified. The maximum limit for this endpoint is 250.
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.
mindist mindist=:distance:unit When using the route action, mindist determines the minimum distance along the route to return the requested data for. A valid unit value must be included in your mindist value, e.g. "5mi", "10km", "50miles". If no unit is provided, your value is assumed to be in meters by default.

The default minimum distance between route data is 5 miles if not specified.
minradius minradius=:distance:unit When requesting the closest results within a circle, the minradius determines how far from the specified location to search to begin searching results. A valid unit value must be included in your minimum radius value, e.g., "5mi", "10km", or "25miles". If no unit is provided, your value is assumed to be in meters by default.
When combined with the radius parameter, donut style queries can be made for point data, such as lightning.
filter filter=:string Predefined filters for limiting the results. The filter value can be a single, comma-delimited or a semicolon delimited string of filter names.
query query=:string Used to filter results based on certain fields in the data set. See Advanced Queries for more details.
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.
skip skip=:number Used to skip over a specific number of results in the data set.
sort sort=:string Used to sort results based on certain fields in the data set. See Sorting for more details.

Supported Filters

The following filters can be passed to the filter parameter to reduce the results that are returned:

hail Returns storm cells that most likely contain hail.
rotating Returns storm cells that show rotation characteristics.
tornado Returns storm cells that contain a tornadic vortex signature (TVS) as determined by NEXRAD radar.
threat Returns storm cells which are potentially threatening
rainmoderate Returns storm cells showing moderate precipitation potential
rainheavy Returns storm cells showing heavy precipitation potential
rainintense Returns storm cells showing intense precipitation potential
conus Returns storm cells within the Continental US (CONUS) only.
Equivalent to: query=country:us,state:!ak,state:!hi,state:!pr

Supported Query Properties

Use the following supported property keys when creating custom queries for your requests:

hailprob Used to query the storm cells hail probability. i.e. query=hail:70 will return only if the hail probability is greater than or equal to 70%.
hailsevere Used to query the storm cells probability of severe hail.
hailsize Used to query the storm cells maximum hail size, in inches.
tvs Used to query if a storm cell is tornadic.
mda, rotation Used to query the degree of a storm cells rotation.
dbz Used to query the precipitation dbz.
type Used to query based on stormcell type: general, hail, rotating, tornado
isgeneral Used to query storm cells that are general / garden variety
1 = true, 0 = false
ishail Used to query storm cells that have at least a 70% probability of hail.
1 = true, 0 = false
isrotating Used to query storm cells that show major rotation
1 = true, 0 = false
istornado Used to query storm cells that show potential tornado characteristics
1 = true, 0 = false
isthreat Used to query storm cells that may be a potential threat
1 = true, 0 = false
name Used to query based on the closest city to the storm cell.
state Query the state the storm cell is in.

Example:
/stormcells/search?query=state:al&limit=100 (Returns up to 100 storm cells in the state of Alabama)
country Used to limit results based on country. Currently only 'us' supported.

Sortable Fields

You can use the following fields to sort data. Review the sorting docs page for more information on the sort functionality.

hailprob Sort the results by the probably of hail.
hailsevere Sort the results by the probably of severe hail.
hailsize Sort the results by the potential hail size.
tvs Sort the results based on being tornadic.
mda, rotation Sort the results based on the amount of rotation in the storm cell.
dbz Sort based on the precipitation rate in DBz
isgeneral Sort the results based storm cells being general / garden variety:
1 = general, 0 = more threatening
ishail Sort based on storm cells most likely to have hail:
1 = hail, 0 = no significant hail potential
isrotating Sort based on storm cells most likely to show major rotation
1 = rotation, 0 = no significant rotation
istornado Sort based on storm cells being potentially tornadic
1 = potentially tornadic, 0 = no significant tornadic features
isthreat Sort based on storm cells showing threatening characteristics
1 = potentially threatening, 0 = no significant threatening characteristics
name Sort the results based on the name of the closet city.
state Sort the results based on the ISO 2-letter state abbreviation.
dt Sort the results based on the date/time of the record.

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]

Returns data for a specific storm cell. In this case Storm Cell ID I9 as reported by Radar station MPX. Returns a single object containing the storm cell information. If no storm cell, then an empty object is returned along with an error code of no data.
/stormcells/mpx_i9?

Returns data for a specific storm cell. In this case Storm Cell ID I9 as reported by Radar station MPX. Returns a single object containing the storm cell information. If no storm cell, then an empty object is returned along with an error code of no data.
/stormcells?p=mpx_i9&

Returns closest single storm cell to the specified point. Result is an array. Empty if no close storm cells.
/stormcells/closest?p=45.25,-95.25&

Returns up to 5 storms cells within 50 miles of zip code 55403 (Minneapolis). Storm cells will be sorted by distance (ascending) from zip code 55403.
/stormcells/closest?p=55403&limit=5&radius=50mi&

Returns up to 1 storm cell within 50 miles of zip code 55403 that has a value for “ob.tvs” greater than 0.
/stormcells/closest?p=55403&query=tvs&

Return all storm cells within 50 miles of zip code 55403 that have a 70%+ probability of hail. Results will be sorted by distance.
/stormcells/closest?p=55403&query=hail:70&limit=0&

Return all storm cells within 50 miles of zip code 55403 that have a 70%+ probability of hail with a hail size between .5 and 2 inches. Results sorted by distance.
/stormcells/closest?p=55403&query=hail:70,hail.size:.5:2&limit=0&

Returns up to 10 storm cells within the rectangle specified with the top left corner of 45.25,-95.25 and the bottom right corner of 35.25,-85.25.
/stormcells/within?p=45.25,-95.25,35.25,-85.25&limit=10&

Returns all storm cells that have an 'ob.tvs' value greater than 0 (meaning a tornadic storm cell) within the rectangle specified with the top left corner of 45.25,-95.25 and the bottom right corner of 35.25,-85.25.
/stormcells/within?p=45.25,-95.25,35.25,-85.25&query=ob.tvs&

Returns storm cells that show hail and tornadic characteristics within the rectangle specified with the top left corner of 45.25,-95.25 and the bottom right corner of 35.25,-85.25.
/stormcells/within?p=45.25,-95.25,35.25,-85.25&filter=tornado,hail&

Returns up to 50 cities within the forecast path of stormcell DMX_CO
/stormcells/affects?p=DMX_CO&limit=50

Returns up to 50 cities with a population of 50,000 or greater that are within the forecast path of stormcell DMX_CO
/stormcells/affects?p=DMX_CO&limit=50&pop=50000

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": [{
        "id": "IWX_S0",
        "loc": {
            "long": -87.601109314399,
            "lat": 41.797875664837
        },
        "ob": {
            "radarID": "IWX",
            "cellID": "S0",
            "cpos": {
                "lat": 41.797875664837,
                "long": -87.601109314399,
                "deg": 288,
                "NM": 90
            },
            "movement": {
                "dirDEG": 324,
                "dir": "NW",
                "dirToDEG": 144,
                "dirTo": "SE",
                "speedKTS": 29,
                "speedMPH": 33,
                "speedKMH": 54,
                "speedKPH": 54
            },
            "tvs": 0,
            "mda": 0,
            "vil": 2,
            "dbzm": 36,
            "ht": 10.3,
            "top": "13.9",
            "topFT": 13900,
            "hail": {
                "probSevere": 0,
                "prob": 0,
                "maxSizeIN": 0,
                "maxSize": "0.00",
                "maxSizeCM": 0
            },
            "location": "7 SE of chicago",
            "timestamp": 1528310281,
            "dateTimeISO": "2018-06-06T13:38:01-05:00"
        },
        "forecast": {
            "locs": [{
                "lat": 41.702272951809,
                "long": -87.523559557893,
                "deg": 285,
                "NM": 85,
                "timestamp": 1528310741,
                "dateTimeISO": "2018-06-06T13:45:41-05:00"
            }, {
                "lat": 41.611015809439,
                "long": -87.416273078217,
                "deg": 282,
                "NM": 79,
                "timestamp": 1528311641,
                "dateTimeISO": "2018-06-06T14:00:41-05:00"
            }],
            "errFcst": 1.3,
            "errMean": 1.8,
            "cone": {
                "narrow": [
                    [41.797875664837, -87.601109314399],
                    [41.598762681855, -87.440627710167],
                    [41.600880998802, -87.435990854657],
                    [41.603059322233, -87.431404295829],
                    [41.605296988609, -87.426869430795],
                    [41.607593316315, -87.422387640916],
                    [41.609947605868, -87.417960291391],
                    [41.612359140128, -87.413588730832],
                    [41.614827184518, -87.409274290859],
                    [41.617350987249, -87.405018285693],
                    [41.619929779546, -87.400822011754],
                    [41.622562775883, -87.396686747268],
                    [41.797875664837, -87.601109314399]
                ],
                "wide": [
                    [41.797875664837, -87.601109314399],
                    [41.574582401611, -87.515222994139],
                    [41.575733858397, -87.510008709431],
                    [41.576952981729, -87.504822174849],
                    [41.57823940025, -87.499664970263],
                    [41.579592722105, -87.494538666607],
                    [41.581012535059, -87.489444825403],
                    [41.582498406624, -87.484384998283],
                    [41.584049884187, -87.479360726522],
                    [41.585666495155, -87.474373540559],
                    [41.587347747091, -87.469424959541],
                    [41.589093127871, -87.464516490853],
                    [41.590902105834, -87.459649629662],
                    [41.592774129948, -87.454825858461],
                    [41.594708629976, -87.450046646619],
                    [41.596705016652, -87.445313449928],
                    [41.598762681855, -87.440627710167],
                    [41.600880998802, -87.435990854657],
                    [41.603059322233, -87.431404295829],
                    [41.605296988609, -87.426869430795],
                    [41.607593316315, -87.422387640916],
                    [41.609947605868, -87.417960291391],
                    [41.612359140128, -87.413588730832],
                    [41.614827184518, -87.409274290859],
                    [41.617350987249, -87.405018285693],
                    [41.619929779546, -87.400822011754],
                    [41.622562775883, -87.396686747268],
                    [41.625249174224, -87.392613751876],
                    [41.627988156267, -87.388604266252],
                    [41.63077888769, -87.384659511724],
                    [41.633620518411, -87.380780689903],
                    [41.63651218284, -87.376968982315],
                    [41.639453000149, -87.373225550044],
                    [41.642442074536, -87.369551533374],
                    [41.645478495501, -87.365948051449],
                    [41.64856133812, -87.362416201921],
                    [41.651689663329, -87.358957060629],
                    [41.65486251821, -87.355571681258],
                    [41.658078936281, -87.352261095029],
                    [41.66133793779, -87.349026310379],
                    [41.664638530014, -87.345868312653],
                    [41.667979707559, -87.342788063809],
                    [41.797875664837, -87.601109314399]
                ]
            }
        },
        "traits": {
            "type": "general",
            "general": 1,
            "hail": 0,
            "rotating": 0,
            "tornado": 0,
            "threat": 0
        },
        "place": {
            "name": "chicago",
            "state": "il",
            "country": "us"
        },
        "profile": {
            "tz": "America\/Chicago"
        },
        "relativeTo": {
            "lat": 41.85003,
            "long": -87.65005,
            "bearing": 145,
            "bearingENG": "SE",
            "distanceKM": 7.077,
            "distanceMI": 4.397
        }
    }]
}
								

{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "id": "IWX_S0",
        "geometry": {
            "type": "GeometryCollection",
            "geometries": [{
                "type": "Polygon",
                "coordinates": [
                    [
                        [-87.601109314399, 41.797875664837],
                        [-87.515222994139, 41.574582401611],
                        [-87.510008709431, 41.575733858397],
                        [-87.504822174849, 41.576952981729],
                        [-87.499664970263, 41.57823940025],
                        [-87.494538666607, 41.579592722105],
                        [-87.489444825403, 41.581012535059],
                        [-87.484384998283, 41.582498406624],
                        [-87.479360726522, 41.584049884187],
                        [-87.474373540559, 41.585666495155],
                        [-87.469424959541, 41.587347747091],
                        [-87.464516490853, 41.589093127871],
                        [-87.459649629662, 41.590902105834],
                        [-87.454825858461, 41.592774129948],
                        [-87.450046646619, 41.594708629976],
                        [-87.445313449928, 41.596705016652],
                        [-87.440627710167, 41.598762681855],
                        [-87.435990854657, 41.600880998802],
                        [-87.431404295829, 41.603059322233],
                        [-87.426869430795, 41.605296988609],
                        [-87.422387640916, 41.607593316315],
                        [-87.417960291391, 41.609947605868],
                        [-87.413588730832, 41.612359140128],
                        [-87.409274290859, 41.614827184518],
                        [-87.405018285693, 41.617350987249],
                        [-87.400822011754, 41.619929779546],
                        [-87.396686747268, 41.622562775883],
                        [-87.392613751876, 41.625249174224],
                        [-87.388604266252, 41.627988156267],
                        [-87.384659511724, 41.63077888769],
                        [-87.380780689903, 41.633620518411],
                        [-87.376968982315, 41.63651218284],
                        [-87.373225550044, 41.639453000149],
                        [-87.369551533374, 41.642442074536],
                        [-87.365948051449, 41.645478495501],
                        [-87.362416201921, 41.64856133812],
                        [-87.358957060629, 41.651689663329],
                        [-87.355571681258, 41.65486251821],
                        [-87.352261095029, 41.658078936281],
                        [-87.349026310379, 41.66133793779],
                        [-87.345868312653, 41.664638530014],
                        [-87.342788063809, 41.667979707559],
                        [-87.601109314399, 41.797875664837]
                    ]
                ]
            }, {
                "type": "LineString",
                "coordinates": [
                    [-87.601109314399, 41.797875664837],
                    [-87.416273078217, 41.611015809439]
                ]
            }, {
                "type": "Point",
                "coordinates": [-87.601109314399, 41.797875664837]
            }]
        },
        "properties": {
            "id": "IWX_S0",
            "loc": {
                "long": -87.601109314399,
                "lat": 41.797875664837
            },
            "ob": {
                "radarID": "IWX",
                "cellID": "S0",
                "cpos": {
                    "lat": 41.797875664837,
                    "long": -87.601109314399,
                    "deg": 288,
                    "NM": 90
                },
                "movement": {
                    "dirDEG": 324,
                    "dir": "NW",
                    "dirToDEG": 144,
                    "dirTo": "SE",
                    "speedKTS": 29,
                    "speedMPH": 33,
                    "speedKMH": 54,
                    "speedKPH": 54
                },
                "tvs": 0,
                "mda": 0,
                "vil": 2,
                "dbzm": 36,
                "ht": 10.3,
                "top": "13.9",
                "topFT": 13900,
                "hail": {
                    "probSevere": 0,
                    "prob": 0,
                    "maxSizeIN": 0,
                    "maxSize": "0.00",
                    "maxSizeCM": 0
                },
                "location": "7 SE of chicago",
                "timestamp": 1528310281,
                "dateTimeISO": "2018-06-06T13:38:01-05:00"
            },
            "forecast": {
                "locs": [{
                    "lat": 41.702272951809,
                    "long": -87.523559557893,
                    "deg": 285,
                    "NM": 85,
                    "timestamp": 1528310741,
                    "dateTimeISO": "2018-06-06T13:45:41-05:00"
                }, {
                    "lat": 41.611015809439,
                    "long": -87.416273078217,
                    "deg": 282,
                    "NM": 79,
                    "timestamp": 1528311641,
                    "dateTimeISO": "2018-06-06T14:00:41-05:00"
                }],
                "errFcst": 1.3,
                "errMean": 1.8
            },
            "traits": {
                "type": "general",
                "general": 1,
                "hail": 0,
                "rotating": 0,
                "tornado": 0,
                "threat": 0
            },
            "place": {
                "name": "chicago",
                "state": "il",
                "country": "us"
            },
            "profile": {
                "tz": "America\/Chicago"
            },
            "relativeTo": {
                "lat": 41.85003,
                "long": -87.65005,
                "bearing": 145,
                "bearingENG": "SE",
                "distanceKM": 7.077,
                "distanceMI": 4.397
            }
        }
    }]
}
								

Response Properties

The following properties will be provided in every response object:

id (string) Cell ID.
ob.timestamp (number) UNIX timestamp of the cell observation.
ob.dateTimeISO (string) ISO 8601 date of the observation.
ob.radarID (string) The radar site ID reporting the cell.
ob.cellID (string) The unique cell identifier.
ob.cpos.lat (number) Current latitude position of the storm.
ob.cpos.long (number) Current longitude position of the storm.
ob.cpos.deg (number) Bearing in degrees of the cell relative to the radar site.
ob.cpos.NM (number) Distance in nautical miles of the cell relative to the radar site.
ob.movement (object) An object containing movement information. If no movement information is available this can be set to NULL.
No movement can occur if the storm cell is newly detected, stationary or ending.
ob.movement.dirDEG (string) The direction the storm is moving in degrees.
ob.movement.dir (number) The cardinal direction the storm is moving.
ob.movement.dirToDEG (string) The direction the storm is moving relative to the reported radar site in degrees.
ob.movement.dirTo (number) The cardinal direction the storm is moving relative to the reported radar site.
ob.movement.speedKTS (number) Speed the storm is moving, in knots.
ob.movement.speedKPH (number) Speed the storm is moving, in kilometers per hour.
ob.movement.speedMPH (number) Speed the storm is moving, in miles per hour
ob.movement.speedKMH (number) Speed the storm is moving, in kilometers per hour
ob.tvs (number) Tornado vortex signature. (TVS)
0 = NO TVS
1 = TVS indicated
ob.mda (number) Mesocyclone rotation. (MESO)
A value from 0 - 25, higher values indicate higher mesoscale rotation
ob.vil (number) Vertically integrated liquid.
ob.dbzm (number) The highest reflectivity found within the storm.
ob.ht (number) The height of the storm structure as received.
ob.htFT (number) The height of the storm structure in feet
ob.htM (number) The height of the storm structure in meters
ob.top (number) Top of the storm in thousands of feet.
ob.topFT (number) Top of the storm in feet.
ob.topM (number) Top of the storm in meters
ob.hail (object) An object containing hail probability and size information. Will be NULL if hail information unavailable for the storm cell.
ob.hail.probSevere (number) Probability that the storm contains severe hail.
ob.hail.prob (number) Probability that the storm contains hail of any size.
ob.hail.maxSize (number) Maximum diameter of hail stones in hundredths of an inch.
ob.hail.maxSizeIN (number) Maximum diameter of hail stones in inches.
ob.hail.maxSizeMM (number) Maximum diameter of hail stones in millimeters.
ob.location (string) The distance and bearing to the closest city.
forecast (object) An object containing forecast information for the storm cell. Will be NULL if forecast information is unavailable, such as with a newly detected storm cell.
forecast.locs (string) Array of forecasted positions for the cell.
forecast.locs[#].lat (number) Forecasted latitude position.
forecast.locs[#].long (number) Forecasted longitude position.
forecast.locs[#].deg (number) Forecasted bearing of the cell relative to the radar site in degrees.
forecast.locs[#].NM (number) Forecasted distance of the cell relative to the radar site in nautical miles.
forecast.locs[#].timestamp (number) UNIX timestamp of the forecasted time at the position.
forecast.locs[#].dateTimeISO (string) ISO 8601 date of forecasted time at the position.
errFcst (number) Error percentage of the forecast from 0 to 1.
errMean (number) Mean error from 0 to 1.
cone (object) An objecting containing the forecast error cone. Will be NULL if forecast information is unavailable, such as with a newly detected storm cell.
cone.narrow (string) Array of lat/long coordinates defining a 5-degree cone of error along the forecast path, which can be used to better determine locations along the path of the storm.
cone.wide (string) Array of lat/long coordinates defining a 20-degree cone of error along the forecast path.
traits (object) Object of storm cell traits
traits.type (string) Storm cell most significant trait / category:
- general
- hail
- rotating
- tornado
traits.general (number) 1 = general storm, 0 = more threatening
traits.hail (number) 1 = at least a 70% probability of hail, 0 = no significant hail threat
traits.rotating (number) 1 = significant rotation, 0 = no significant rotation
traits.tornado (number) 1 = potential tornadic characteristics, 0 = no significant tornadic characteristics
traits.threat (number) 1 = potential threatening storm cell, 0 = no significant potential threat
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.
relativeTo.lat (number) Latitude coordinate of the location used for the request. This may be different than the record's loc.lat value if there was no record exactly at the request location.
relativeTo.long (number) Longitude coordinate of the location used for the request. This may be different than the record's loc.long value if there was no record exactly at the request location.
relativeTo.bearing (number) Bearing in degrees of the record's location relative to the location used for the request.
relativeTo.bearingEng (string) Cardinal direction of the record relative to the location used for the request.
relativeTo.distanceKM (number) Distance, in kilometers, from the requested location to the record's actual location.
relativeTo.distanceMI (number) Distance, in miles, from the requested location to the record's actual location.

Last modified: July 11, 2023