Alerts API

The Alerts API provides real-time severe weather alerts from the following providers.

National Weather Service

Severe weather alerts for the United States are provided by the National Weather Service. These alerts cover events such as Flood Warnings, Severe Thunderstorm Warnings, and Special Weather Statements.

Helios beta

Alerts generated by Helios are based on the sensor measurements from the Observations API. These alerts represent regional areas with a high detection confidence and currently include: Road Wetness Watch, Poor Visibility Watch, Heavy Precip Watch.

Return a list of alerts matching the provided spatial, text, or metadata filters

Request

GET  https://api.helios.earth/v1/alerts  or
POST https://api.helios.earth/v1/alerts/_search

Query Parameters

When submitting a search using a GET request, all query parameters are specified as part of the query string. For POST requests, query parameters can either be submitted using a content type of application/json or x-www-form-urlencoded. See API Basics for more information.


q Query string that searches across multiple text fields
event Alert event type, e.g. torando watch, severe thunderstorm warning
state Name of the state where the alert is located e.g. New York, California
country Name of the country where the alert is located e.g. United States
bbox Geospatial bounding box query, specified in GeoJSON format e.g. -180,-90,180,90
polygon Comma separated coordinate pairs. Each coordinate pair consists of the longitude and latitude, separated by a space. It is recommended that the first and last coordinate pairs be equal to properly close the polygon.

e.g. -105 40,-100 36,-110 38,-105 40
lat, lon, radius Geospatial point radius query. lat and lon are specified in degrees. Radius is optional and can be specified in either meters (no units), kilometers, or miles e.g. 10000 or 10km or 10mi. If no radius is specified, a default value of 10km is assumed.
polyline, polyline_precision, polyline_radius Geospatial polygon search using the encoded polyline format used by routing providers. The polyline_precision defaults to a precision of 5, which is used by Google Maps. For OSRM-based routing providers like Mapbox Directions, use a precision value of 6. The polyline_radius provides a buffer around the supplied polyline and is specified in kilometers, with a default value of 1.

Note: Polylines can be quite large for complex routes and there is a limit on the size of a query string for GET requests, so it is recommended that you use POST requests to submit searches that include this parameter.
effective_min, effective_max Alert effective time, specified in UTC as an ISO 8601 string (e.g. 2013-07-01 or 2013-07-01T12:34:56.000Z).
expires_min, expires_max Alert expires time, specified in UTC as an ISO 8601 string (e.g. 2013-07-01 or 2013-07-01T12:34:56.000Z).
urgency past, future, expected, immediate, or unknown_urgency
severity minor, moderate, severe, extreme, or uknown_severity
certainty unlikely, possible, likely, observed, or unknown_certainty
expired By default, current alerts are returned. Specify true to return previously expired alerts or any to return both current and expired alerts.
limit Limit value for pagination. Defaults to 10.
skip Skip value for pagination. Defaults to 0.
sort Sort parameter: event, state, country, effective, expires, urgency, severity, and certainty are currently allowed.
sort_dir Sort direction: asc or desc (default is asc)
aggs

Aggregate and summarize the results set based on the following attributes: event, state, urgency, severity, certainty.


Multiple aggregations can be requested using array syntax or by listing them comma-delimited, e.g: 

aggs[]=event&aggs[]=state
aggs=event,state

For each requested aggregation, up to ten values and their respective alert counts will be returned. For instance, if the event aggregation is requested, the results will include the ten event types with the highest number of alerts matching the specified search query parameters, along with the total count for each of those events.

Response

GeoJSON Feature Collection

HTTP 200

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "LA1258631A7ED0.TornadoWarning.1258631A9AF0LA.LIXTORLIX.17da17441c9808bc0e5d397f3e2779b0",
      "bbox": [-90.29,29.09,-90.12,29.37],
      "geometry": {
        "type": "Polygon",
        "coordinates": [...]
      },
      "properties": {
        "origin": "NWS",
        "event": "Tornado Warning",
        "headline": "Tornado Warning issued August 29 at 5:28AM CDT until August 29 at 6:00AM CDT by NWS",
        "states": ["Louisiana"],
        "areaDesc": "Lafourche",
        "description": "..",
        "effective": "2017-08-29T10:28:00.000Z",
        "expires": "2017-08-29T11:00:00.000Z",
        "updated": "2017-08-29T10:28:00.000Z",
        "urgency": "Immediate",
        "severity": "Extreme",
        "certainty": "Observed",
        "status": "Actual"
      }
    }
  ],
  "properties": {
    "limit": 1,
    "skip": 0,
    "total": 15,
    "aggs": {
      "state": {
        ["key": "Louisiana", "doc_count": 10]
      }
    }
  }
}

View example
This API method is currently in beta and subject to change.

All

Return all alerts (Helios and third-party providers) for the given time as a single response

Request

GET https://api.helios.earth/v1/alerts/_all/:time.json

URL Parameters

time UTC time in yyyyddmmThhmmZ format. Data files are provided "on the tens", e.g. (20180801T1200Z, 20180801T1210Z, etc.) and are generally available 10 minutes after the given time period.

Response

HTTP 302

Note: The redirect URL is a signed URL that is valid for 15 minutes. Do not try to re-add any Helios authorization headers when following the redirect or you will not be able to retrieve the data.

Redirect Response

HTTP 200
application/json

The redirect response is a GeoJSON Feature Collection in the same format as that provided by the Search method, with the exception that there is no properties attribute.

Show

Return the attributes for a single alert

Request

GET https://api.helios.earth/v1/alerts/:id

Response

HTTP 200, GeoJSON Feature