National Weather Service Advisories (Beta)

In the United States, the National Weather Service (NWS) issues a variety of weather statements that alert the public to adverse and dangerous weather conditions. This API will provide any active alerts near a Field Location. You have the option to filter to a specific type of alert (such as severe storms or winter weather) and a level of significance (warnings, watches, advisories, and statements).

Important: This API only works with locations in the United States.

Note: The NWS does not issue separate advisories for hail. Hail can be present in a variety of storms, but hail that actually poses a threat to crops and property (1" or greater diameter) is typically only present in severe thunderstorms and tornadoes. When hail might be present in other types of smaller storms, the NWS may issue a Special Weather Statement. Specifics regarding hail risk are detailed in the message body, including those for smaller storms.

Note: This API technically remains in beta, but we are planning no changes to the API design itself.

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/weather/fields/{fieldId}/advisories
  • Returns any active advisories that match your filters surrounding the field location.

Parameters

Parameter Description Valid Values
{fieldId} The ID of the field location for which you want weather. A string

Query String Parameters

Query Parameter Name Description Valid Values
radius How far away from the field should the system look for current advisories. Default is 5 miles An integer followed by units, for example:
10mi
10km
significance The NWS issues advisories of a different levels of severity (or "significance"). By default, the API will return any warning, watch, or advisory. Use this parameter to filter down to just one or two of those levels; include more than option by comma-separating the values. Note: the NWS issues more messages such as general outlooks, but these are never included in this API. warnings,
watches
advisories
statements
types By default, advisories for any weather phenomena will be included, but you can filter down to a select set using any of the categories at the right. Combine multiple categories with commas. See the table below to know what phenomena are included in which category. severe
winter
wind
flood
storms
extremetemperatures
nonprecipitation

Request Body

None

HTTP Headers

Remember to always send your OAuth2 Access Token in the Authorization header (see Authentication). This API doesn't require any additional headers.

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. No additional headers are returned.

Response Body

Format

{
  "alerts": [
    {
      "location": {
        "latitude": {latitude},
        "longitude": {longitude},
        "fieldId": "{fieldId}"
      },
      "dateTimeIssued": "{dateTimeIssued}",
      "dateTimeBegins": "{dateTimeBegins}",
      "dateTimeExpires": "{dateTimeExpires}",
      "phenomena": {
        "name": "{phenomenaName}",
        "category": "{phenomenaCategory}"
      },
      "significance": "{significance}",
      "title": "{title}",
      "message": "{message}",
      "areaAffected": {
        "name": "{areaName}",
        "state": "{areaState}",
        "zipcodes": {zipCodeArray}
      }
    }
  ],
  "_links": {
    "self": {
      "href": "{selfLink}"
    },
    "curies": [
      {
        "name": "awhere",
        "href": "http://awhere.com/rels/{rel}",
        "templated": true
      }
    ],
    "awhere:field": {
      "href": "{fieldLink}"
    }
  }
}

Note: if there are no alerts, the alerts array will be empty.

Property Descriptions

Name Description
location The location the weather is for, including the geolocation and repeating the supplied Field ID.
{dateTimeIssued} The timestamp of when the NWS issued the advisory.
{dateTimeBegins} The timestamp of when the advisory begins being in effect.
{dateTimeExpires} The timestamp of when the advisory is expected to end.
{phenomenaName} The formal name of the weather phenomena described by the advisory.
{phenomenaCategory} The category that captures the phenomena; essentially the same value as the types query string parameter described above.
{significance} The level of severity for the advisory. Will be either Warning, Watch, Advisory, or Statement
{title} The advisory title, typically a combination of phenomena and significance. Note that the NWS issues advisories with text in all-capital letters.
{message} The detailed message from the NWS describing the advisory. Note that the NWS issues advisories in all-capital letters and with line break characters included. This API does not echo the full detail of the advisory, which normally includes machine-readable codes; instead, this API returns the human-readable content.
{areaName} and {areaState} The human-friendly name of the area affected by the advisory, often a city name or county names.
{zipCodeArray} An array containing the US ZIP codes affected by the advisory.
{selfLink} The URI you can use to retrieve a specific area's current advisories (useful for caching a response).
awhere:field The URI you can use to retrieve the field location information.

Advisory Type Categories

The types query string parameter allows you to filter the list of advisories down to a set of specific weather phenomena. The table below describes each of the categories (the allowed values of types) and which phenomena will be included.

Category Included Phenomena
severe
  • Storms
  • Severe Thunderstorms
  • Tornadoes
  • Hurricanes (including landfallen)
  • Tropical Storms (including landfallen)
winter
  • Blowing Snow
  • Blizzards
  • Extreme Cold
  • Frost
  • Freeze
  • Heavy Snow
  • Hard Freeze
  • Sleet
  • Ice Storm
  • Snow
  • Ice Accretion
  • Wind Chill
  • Winter Storm
  • Winter Weather
  • Freezing Fog
  • Freezing Rain
  • Lake Effect Snow and Blowing Snow
  • Lake Effect Snow
  • Snow and Blowing Snow
  • Storms
wind
  • Brisk Winds
  • Gales
  • Hurricane-Force Winds
  • High Winds
  • Lake Winds
  • Winds (General)
  • Extreme Wind
flood
  • Coastal Floods
  • Areal Floods
  • Flash Floods
  • Floods
  • Lakeshore Floods
  • Hydrologic
storms
  • Storms (general)
  • Severe Thunderstorms
  • Winter Storms
  • Ice Storms
extremetemperatures
  • Extreme Cold
  • Excessive Heat
  • Heat
  • Wind Chill
nonprecipitation
  • Dust Storms
  • Blowing Dust
  • Dense Fog
  • Fire Weather (inc. Red Flag)
  • Dense Smoke
  • Heat
  • Excessive Heat
  • Ashfall