Alerts

URL Path

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

Data Coverage

India, Brazil, South Africa, South Korea, Mexico, US, Canada, Europe, Australia

Update Interval

Near real-time

Time Range

Latest

The alerts endpoint (formerly known as the advisories endpoint) provides access to all currently active US, Canadian, and European alerts as issued by the National Weather Service (opens in a new tab) (NWS), Environment Canada (opens in a new tab) (EC), MeteoAlarm (opens in a new tab), the UK Met Office, (opens in a new tab)and the Australian Bureau of Meteorology. (opens in a new tab) The default limit for this endpoint is 10 to ensure the response contains all alerts for a single location with one request.

The NWS and EC issue various weather warnings, watches, advisories, and statements. Within the USA, alerts are issued by either weather zone or county. Within Canada, alerts are issued by Canadian Location Codes (opens in a new tab).

Within Europe, MeteoAlarm issues weather alerts as warnings, with a severity indicator of moderate, severe, or extreme.

Note: MeteoAlarm issues European alerts for today and tomorrow separately. The UK Met Office issues alerts for today and the next 4 days. The API currently provides access to today's alerts.

Supported Alert Types

Please refer to the full list (opens in a new tab) of available alerts, type, and color codes.

The alert type codes may be passed in the type element of the query parameter and correspond to the details.type in the response output.

Requests

Every request to the endpoint must include one of the supported actions in the url.

https://data.api.xweather.com/alerts/{action}?client_id={client_id}&client_secret={client_secret}&{params}

Supported Actions

The following actions are supported with the /alerts 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.
route	Type: stringAllows you to pass several coordinates along a custom route to return data points at each location. 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

id (string)

The unique ID attribute identifying the alert. The ID is based on a combination of the details.loc, details.type and an internal event ID. Normally, the same ID will be utilized if the weather offices update the alert.

dataSource (string)

The source of the official alert information. Potential values include:
- noaa_nws
- envca
- meteoalarm
- ukmet

loc.long (number)

The place or nearest place to the record.

loc.lat (number)

The latitude coordinate of the record.

active (boolean)

True if the alert is still active and has not expired.

details.type (string)

The valid-time event code for the alert. Review the list of supported Alert Types.

details.name (string)

The type name for the alert.

details.loc (string)

The weather zone for the alert.

details.emergency (boolean)

Set to true if this is an emergency-specific alert, such as a tornado emergency.

details.priority (number)

The numeric priority of the alert. The lower the priority the higher the alert significance. US alerts typically match the NOAA defined alert priorities. There may be some minor differences from the NOAA list, especially for international locations.

details.color (string)

The 6 character hex color code for the alert. Corresponds to the Alert types/colors.

details.cat (string)

The default category of the alert type. May be null for non common alerts.

details.body (string)

The shortened and formatted version of the alert body text. Primarily for US alerts, removing the National Weather Service alert header information. Often the same as the bodyFull for Canadian and European alerts.

details.bodyFull (string)

The complete, unmodified version of the alert body text, including headers.

timestamps.issued (number)

UNIX timestamp when the alert was initially issued for the location. This value will not normally change during the lifetime of the alert.

timestamps.issuedISO (string)

ISO 8601 date of the time when the initially issued for the location. This value will not normally change during the lifetime of the alert.

timestamps.begins (number)

UNIX timestamp when the alert goes into effect. Often this will match the issue/updated time, though for some alerts, such as winter storm warnings, this may be set to a future date/time.

timestamps.beginsISO (string)

ISO 8601 date of the time when the alert goes into effect. Often this will match the issue/updated time, though for some alerts, such as winter storm warnings, this may be set to a future date/time.

timestamps.expires (number)

UNIX timestamp when the alert expires.

timestamps.expiresISO (string)

ISO 8601 date of the time when the alert expires.

timestamps.updated (number)

UNIX timestamp when the alert was updated. For a new alert, the issue and updated will normally match. If an alert is updated during its lifetime, this updated timestamp will change.

timestamps.updateISO (string)

ISO 8601 date of when the alert was updated. For a new alert, issue and updated will normally match. If an alert is updated during its lifetime, this updated timestamp will change.

timestamps.added (number)

UNIX timestamp when the issuance or last update for the alert was received and stored in the DB after initial issuance.

timestamps.addedISO (string)

ISO 8601 date when the issuance or last update for the alert was received and stored in the DB after initial issuance.

poly (string)

DEPRECATED. A comma-delimited string of latitude, longitude coordinates defining the small polygon boundary for this alert; typically used for certain alerts, such as tornado and severe thunderstorm warnings. NULL if the alert does not include a small polygon boundary.

This field has been deprecated in favor of the geoPoly attribute.

geoPoly ()

A GeoJSON polygon defining the small polygon boundary for this alert; typically used for certain alerts, such as tornado and severe thunderstorm warnings. NULL if the alert does not include a small polygon boundary.

When filter=geo is utilized, if no small polygon exists for the alert, the polygon for the weather zone, fire zone, county or CLC they alert is issued for will be returned.

includes.fips (array)

If a US alert will be a list of US counties in the XX### format, where XX is the state two digit fips number and ### is the 3 digit county fips number. If a Canadian alert will be null.

includes.counties (array)

If a US alert will be a list of US counties in the XXC### format, where XX is the state abbreviation and ### is the 3 digit county fips number. If a Canadian alert will be null.

includes.wxzones (array)

If a US alert will be a list of US public weather zones in the NOAA XXZ### format, where XX is the state abbreviation and ### is the 3 digit public zone id. If a Canadian alert will be a list of Canadian location codes (CLCs)

includes.zipcodes (array)

List of US zip codes that are affected by the alert. Only US zip codes, where the zip code centroid are within the alert, including any small polygon will be returned.

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.tz (string)

Timezone name of the location, such as America/New_York.

[
  {
    "id": "71a135f8820e811ca702ba33e583583e",
    "loc": {
      "long": -103.5645,
      "lat": 37.3221
    },
    "dataSource": "noaa_nws",
    "details": {
      "type": "WS.W",
      "name": "WINTER STORM WARNING",
      "loc": "COZ094",
      "emergency": false,
      "priority": 25,
      "color": "FF69B4",
      "cat": "winter",
      "body": "...WINTER STORM WARNING REMAINS IN EFFECT UNTIL 5 PM MST\nTHURSDAY...\n\n* WHAT...Heavy snow. Additional snow accumulations of 4 to 11\ninches...with the greatest amounts over the southern facing\nslopes. \n\n* WHERE...Southern Sangre de Cristo Mountains, Huerfano and Las\nAnimas Counties including the Southern I-25 Corridor and Raton \nPass.\n\n* WHEN...Until 5 PM MST Thursday.\n\n* IMPACTS...Travel could be very difficult. The hazardous\nconditions could impact the evening and morning commute.\n\nIf you must travel, keep an extra flashlight, food, and water in\nyour vehicle in case of an emergency. \n\nThe latest road conditions for the state you are calling from can\nbe obtained by calling 5 1 1.",
      "bodyFull": "WWUS45 KPUB 132200\nWSWPUB\n\nURGENT - WINTER WEATHER MESSAGE\nNational Weather Service Pueblo CO\n300 PM MST Wed Dec 13 2023\n\n\n\nCOZ074-075-087-088-094-140600-\n/O.CON.KPUB.WS.W.0017.000000T0000Z-231215T0000Z/\nSouthern Sangre de Cristo Mountains Between 7500 and 11000 Feet-\nSouthern Sangre de Cristo Mountains Above 11000 Feet-\nWalsenburg Vicinity/Upper Huerfano River Basin Below 7500 Feet-\nTrinidad Vicinity/Western Las Animas County Below 7500 Feet-\nEastern Las Animas County-\n300 PM MST Wed Dec 13 2023\n\n\n\n...WINTER STORM WARNING REMAINS IN EFFECT UNTIL 5 PM MST\nTHURSDAY...\n\n* WHAT...Heavy snow. Additional snow accumulations of 4 to 11\ninches...with the greatest amounts over the southern facing\nslopes. \n\n* WHERE...Southern Sangre de Cristo Mountains, Huerfano and Las\nAnimas Counties including the Southern I-25 Corridor and Raton \nPass.\n\n* WHEN...Until 5 PM MST Thursday.\n\n* IMPACTS...Travel could be very difficult. The hazardous\nconditions could impact the evening and morning commute.\n\nPRECAUTIONARY/PREPAREDNESS ACTIONS...\n\nIf you must travel, keep an extra flashlight, food, and water in\nyour vehicle in case of an emergency. \n\nThe latest road conditions for the state you are calling from can\nbe obtained by calling 5 1 1.\n\n&&"
    },
    "timestamps": {
      "issued": 1702416600,
      "issuedISO": "2023-12-12T14:30:00-07:00",
      "begins": 1702504800,
      "beginsISO": "2023-12-13T15:00:00-07:00",
      "expires": 1702598400,
      "expiresISO": "2023-12-14T17:00:00-07:00",
      "updated": 1702504800,
      "updateISO": "2023-12-13T15:00:00-07:00",
      "added": 1702504842,
      "addedISO": "2023-12-13T15:00:42-07:00",
      "created": 1702416665,
      "createdISO": "2023-12-12T14:31:05-07:00"
    },
    "poly": "",
    "geoPoly": null,
    "includes": {
      "fips": [
        "08023",
        "08055",
        "08071"
      ],
      "counties": [],
      "wxzones": [
        "COZ074",
        "COZ075",
        "COZ087",
        "COZ088",
        "COZ094"
      ],
      "zipcodes": [
        "81020",
        "81024",
        "81027",
        "81040",
        "81046",
        "81049",
        "81055",
        "81059",
        "81064",
        "81081",
        "81082",
        "81089",
        "81091"
      ]
    },
    "place": {
      "name": "eastern las animas county",
      "state": "co",
      "country": "us"
    },
    "profile": {
      "tz": "America/Denver"
    },
    "active": true
  }
]

Endpoints