Alert Details

The Weather Alert Details API provides the details for a single requested event for weather watches, warnings, statements and advisories issued by the NWS (National Weather Service), Environment Canada and MeteoAlarm. These weather alerts can provide crucial life-saving information. Weather alerts can be complicated and do not always follow consistent standards, format and rules. The Weather Company (TWC) strives to ensure that the information is consistent from all of the different sources but the content is subject to change whenever there is an update from the authoritative source.

The Weather Alert Details API returns additional details related to Severe Thunderstorms, Tornadoes, Earthquakes, Floods, etc . This API also returns non-weather alerts such as Child Abduction Emergency and Law Enforcement Warnings.

Overview

  • Domain Portfolio: Alerts
  • Domain: Alerts
  • Usage Classification: Standard
  • Geography: US, Canada, Japan, Western Europe, Australia
  • Attribution Required: YES
  • Attribution Requirements: Clients must provide data source attribution on anywhere data is displayed.
Note:

The attribution phrase must display: “Issued by <Office Name> - <Office Admin District Code>, <Office Country Code>, <Source>, <Disclaimer>”.

  • Example: Issued by National Weather Service - Bismarck, US

  • Example: Issued by Central Institute for Meteorology and Geodynamics - Austria, EUMETNET-Meteoalarm, Disclaimer: "Time delays between this website and <a href='http://meteoalarm.eu/'>Meteoalarm.eu</a> are possible. For the most up-to-date information about alert levels as published by the participating National Meteorological Services, please visit <a href='http://meteoalarm.eu/'>Meteoalarm</a>."

HTTP Headers and Data Lifetime - Caching and Expiration

For details on appropriate header values as well as caching and expiration definitions, please see The Weather Company Data | API Common Usage Guide.

Translated Fields:

This TWC API handles the translation of phrases. However, when formatting a request URL a valid language must be used (see The Weather Company Data | API Common Usage Guide)

  • countryName
  • disclaimer
  • headlineText
  • eventDescription
  • officeAdminDistrict
NOTE: In order to use this API, user must FIRST do the following0:
  1. Run Weather Company Data - Core - v3 - Alerts - Weather Alerts - Headlines
  2. Obtain a ‘detailKey’ from running the operation above.
  3. Use the obtained ‘detailKey’ as the required parameter ‘alertId’ in running this API

Table 1. URL Construction
Atomic API URL Examples Aggregate Product Name

Request by Alert ID: Required Parameters: alertId, format, language, apiKey

https://api.weather.com/v3/alerts/detail?alertId=<alertId>&format=json&language=en-US&apiKey=yourApiKey

v3alertsDetail* (See note at end of document)
https://api.weather.com/v3/alerts/detail?alertId=c092289d-1282-318a-b0c6-ab4c95ee3c57&format=json&language=en-US&apiKey=yourApiKey v3alertsDetail* (See note at end of document)

Weather Alert Narrative Text and Language Support

Beyond the translated fields indicated above, language returned is not determined by TWC API but by the nation where alert is located. Language Codes supported for each country appear in the table below:

Country Language Language Code Parameter
United States US English, Mexico Spanish (limited distribution) en-US, es-MX
Austria Austrian German, UK English de-DE, en-GB
Australia Australian English, US English en-AU, en-US
Belgium Dutch, Belgium French, German, UK English nl-BE ,fr-BE, de-DE, en-GB
Bosnia-Herzegovina Bosnian, UK English bs-BA, en-GB
Bulgaria UK English, Bulgarian en-GB, bg-BG
Canada Canadian English, Canadian French en-CA, fr-CA
Croatia UK English, Croatian en-GB, hr-HR
Cyprus Greek, Turkish el-GR,tr-TR
Czech Republic UK English, Czech en-GB, cs-CZ
Denmark Danish, UK English da-DK, en-GB
Estonia UK English, Estonian, Russian et-EE, en-GB, ru-RU
Finland Finnish, Swedish, UK English fi-FI, sv-FI, en-GB
France French France, UK English fr-FR, en-GB
Germany German, UK English, French France, Spanish Spain de-DE, en-GB, fr-FR, es-ES
Greece Greek, UK English el-GR, en-GB
Hungary UK English, Hungarian en-GB hu-HU
Iceland Icelandic, UK English is-IS, en-GB
Ireland UK English en-GB
Israel UK English, Hebrew en-GB, he-IL
Italy Italian, UK English it-IT, en-GB
Japan Japanese ja-JP
Latvia Latvian, UK English lv-LV, en-GB
Lithuania Lithuanian, UK English lt-LT, en-GB
Luxembourg German, France French, UK English de-DE, fr-FR, en-GB
Macedonia Macedonian, UK English mk-MK, en-GB
Malta UK English en-GB
Moldova Romanian en-GB
Montenegro UK English en-GB
Netherlands Dutch, UK English nl-NL, en-GB
Norway Norwegian, UK English no-NO, en-GB
Poland UK English, Polish en-GB, pl-PL
Portugal Portuguese, UK English pt-PT, en-GB
Romania Romanian, UK English ro-RO, en-GB
Serbia UK English, Serbian en-GB, sr-RS
Slovakia UK English, Slovak en-GB, sk-SK
Slovenia Slovenian, UK English sl-SI, en-GB
Spain Spain Spanish, UK English es-ES, en-GB
Sweden Swedish, UK English sv-SE, en-GB
Switzerland UK English en-GB
United Kingdom UK English en-GB

Data Elements & Definitions

Note: Field names are sorted alphabetically in the table below for presentation purposes. The table below does not represent the sort order of the API response.

Field Name Description Type Range Sample Nulls Allowed
"alertDetail.object"   object     N
adminDistrict Admin district name string   Montana Y
adminDistrictCode Admin district code string   MT Y
areaId Location code for a location where the event occurs. string   MTC035 N
areaName Mixed case location name string   Glacier N
areaTypeCode This identifies type of location. string

C = county

Z = zone

CLC=Canada Location

C N
certainty Certainty text string

Observed – Determined to have occurred or to be ongoing

Likely - Likely (p > ~50%)

Possible - Possible but not likely (p <= ~50%)

Unlikely - Not expected to occur (p ~ 0)

Unknown - Certainty unknown

Observed N
certaintyCode Certainty code integer

1 - Observed

2 - Likely

3 - Possible

4 - Unlikely

5 - Unknown

1 N
countryCode country code of the location string   US N
countryName country name string   UNITED STATES OF AMERICA N
detailKey detail record key string   77128ec9-cebe-46b2-8d72-d1f6860454e7 N
disclaimer Disclaimer for data string   null Y
effectiveTimeLocal The effective date and time of the information in the alert message. string valid date 2017-10-07T12:30:00-05:00 Y
effectiveTimeLocalTimeZone Time Zone Abbreviation for effective time string valid timezone EDT Y
eventDescription Event Description string   Tornado Warning N
eventTrackingNumber Event Tracking Number string 4 digit number or a checksum 160 N
expireTimeLocal The expire date and time of the information in the alert message. string valid date 2017-10-07T19:30:00-05:00 N
expireTimeLocalTimeZone Time Zone Abbreviation string valid timezone EDT N
expireTimeUTC Expire date and time in UTC epoch valid Epoch time 1373914800 N
headlineText Headline text of an event for the location string

{event} is in effect

{event} until {DOW HH:MM AM/PM TZCODE}

{event} from {DOW HH:MM AM/PM TZCODE} until {DOW HH:MM AM/PM TZCODE}

Flood Warning until SAT 12:30PM CDT N
ianaTimeZone IANA time code string Valid timezone America/Chicago Y
identifier This is the checksum value uniquely identifies a bulletin string checksum a463d8adbd563a981673b1beab2b04994e80078a N
issueTimeLocal Alert issuance time string valid date 2017-10-07T11:30:00-05:00 N
issueTimeLocalTimeZone Time zone Abbreviation string valid timezone CDT N
latitude centroid latitude of a location where the event occurs. decimal   48.65 Y
longitude centroid longitude of a location where event occurs. decimal   -113.13 Y
messageType The nature of the alert message string

New - Initial information

Update - Updates existing message

Cancel - Cancels the earlier message

New N
messageTypeCode The nature of the alert message code integer

1 - New

2 - Update

3 - Cancel

2 N
officeAdminDistrict Office Admin District string   Montana Y
officeAdminDistrictCode Issuing Office State Code string   MT Y
officeCode Issuing Office code string   KTFX N
officeCountryCode Issuing Office Country Code string   US Y
officeName Issuing Office Name string   Great Falls Y
onsetTimeLocal The onset date and time of the information in the alert message. (Canada only) string valid date 2017-10-07T17:30:00-05:00 Y
onsetTimeLocalTimeZone Time Zone Abbreviation for onset time string valid timezone EDT Y
phenomena Phenomena code of an event string   TO N
processTimeUTC Alert process time in SUN integer valid unix time UTC 1475863030000 N
productIdentifier Product Line Identifier string Refer Inbound PIL/Event Tab TOR N
severity Severity of the subject event of the alert message string

Extreme - Extraordinary threat to life or property

Severe - Significant threat to life or property

Moderate - Possible threat to life or property

Minor – Minimal to no known threat to life or property

Unknown - Severity unknown

Severe N
severityCode Severity code of the subject event of the alert message integer

1 - Extreme

2 - Severe

3 - Moderate

4 - Minor

5 - Unknown

1 N
significance Equated to Type - such as a Watch, Warning or Advisory string   W N
source Originating source of alert string   NWS N
synopsis Brief summary string   *text too large to display here Y
urgency Urgency text string

Immediate - Responsive action SHOULD be taken immediately

Expected - Responsive action SHOULD be taken soon (within next hour)

Future - Responsive action SHOULD be taken in the near future

Past - Responsive action is no longer required

Unknown - Urgency not known

Expected N
urgencyCode Urgency code integer

1 - Immediate

2 - Expected

3 - Future

4 - Past

5 - Unknown

2 N
endTimeLocal the date and time that a alert is expected to end. It may be null for indefinitely long events (in which case the headline will indicate that the event is “in effect”) string Valid date 2021-10-04T16:30:00-04:00 Y
endTimeLocalTimeZone the time zone for endTimeLocal string Valid timezone EDT Y
endTimeUTC the end date and time in UTC integer Valid unix time UTC 1633379400 Y
"categories.object"   object     N
category The category description of the subject event of the alert message string

Geo - Geophysical (inc. landslide)

Met - Meteorological (inc. flood)

Safety - General emergency and public safety

Security - Law enforcement, military, homeland and local/private security

Rescue - Rescue and recovery

Fire - Fire suppression and rescue

Health - Medical and public health

Env - Pollution and other environmental

Transport - Public and private transportation

Infra - Utility, telecommunication, other non-transport infrastructure

CBRNE – Chemical, Biological, Radiological, Nuclear or High-Yield Explosive threat or attack

Other - Other events

Met N
categoryCode The code denoting the category of the subject event of the alert message integer

1 - Geo

2 - Met

3 - Safety

4 - Security

5 - Rescue

6 - Fire

7 - Health

8 - Env

9 - Transport

10 - Infra

11 - CBRNE

12 - Other

2 N
"responseTypes.object"   object     N
responseType Description of action recommended for the target audience string

Shelter – Take shelter in place or per instruction

Evacuate – Relocate as instructed in the instruction

Prepare – Make preparations per the instruction

Execute – Execute a pre-planned activity identified in instruction

Avoid – Avoid the subject event as per the instruction

Monitor – Attend to information sources as described in instruction

Assess – Evaluate the information in this message. (This value SHOULD NOT be used in public warning applications.)

AllClear – The subject event no longer poses a threat or concern and any follow on action is described in <instruction>

None – No action recommended

Evacuate N
responseTypeCode The code denoting the type of action recommended for the target audience integer

1 - Shelter

2 - Evacuate

3 - Prepare

4 - Execute

5 - Avoid

6 - Monitor

7 - Assess

8 - AllClear

9 - None

2 N
"flood.object"   object     Y
floodCrestTimeLocal Flood Crest date time string valid date 2017-10-07T21:30:00-05:00 Y
floodCrestTimeLocalTimeZone Flood crest date time zone abbeviation string valid timezone EDT Y
floodEndTimeLocal Flood End date time string valid date 2017-10-07T23:30:00-05:00 Y
floodEndTimeLocalTimeZone Flood end date time zone abbeviation string valid timezone EDT Y
floodImmediateCause Flood Immediate Cause description string

Excessive Rainfall

Snowmelt

Rain and Snowmelt

Dam or Levee Failure

Ice Jam

Glacier-Dammed Lake Outburst

Rain and/or Snowmelt and/or Ice Jam

Upstream Flooding plus Storm Surge

Upstream Flooding plus Tidal Effects

Elevated Upstream Flow plus Tidal Effects

Wind and/or Tidal Effects

Upstream Dam or Reservoir Release

Other Multiple Causes

Other Effects

Unknown

Excessive Rainfall Y
floodImmediateCauseCode Flood Immediate Cause code string

ER Excessive Rainfall

SM Snowmelt

RS Rain and Snowmelt

DM Dam or Levee Failure

IJ Ice Jam

GO Glacier-Dammed Lake Outburst

IC Rain and/or Snowmelt and/or Ice Jam

FS Upstream Flooding plus Storm Surge

FT Upstream Flooding plus Tidal Effects

ET Elevated Upstream Flow plus Tidal Effects

WT Wind and/or Tidal Effects

DR Upstream Dam or Reservoir Release

MC Other Multiple Causes

OT Other Effects

UU Unknown

NO Y
floodLocationId Flood Location Identifier code string Any Valid NWS flood location identifier SMBM8 Y
floodLocationName Flood Location Identifier Name string Any valid NWS flood location identifier or N/A Saint Mary River at International boundary N
floodRecordStatus Flood Record Status description string

A record flood is not expected

Near record or record flood expected

Flood without a period of record to compare

For areal flood warnings, areal flash flood products, and flood advisories (point and areal)

N/A

Near record or record flood expected N
floodRecordStatusCode Flood Record Status code string

NO A record flood is not expected

NR Near record or record flood expected

UU Flood without a period of record to compare

OO For areal flood warnings, areal flash flood products, and flood advisories (point and areal)

NR Y
floodSeverity Flood Severity Description string

None

N/A

Minor

Moderate

Major

Unknown

1 Y
floodSeverityCode Flood Severity Code string

N None

0 N/A

1 Minor

2 Moderate

3 Major

U Unknown

0 Y
floodStartTimeLocal Flood Start date Time string valid date 2017-10-07T20:30:00-05:00 Y
floodStartTimeLocalTimeZone Flood start date time zone abbreviation string valid timezone EDT Y
"texts.object"   object     Y
description   string   * text too large to display here Y
instruction   string   * text too large to display here Y
languageCode language for texts string See documents for supported languages en-US Y
overview   string   * text too large to display here Y
"polygon.object"   object     Y
lat latitude decimal   48.65 Y
lon longitude decimal   -113.13 Y
“supplement.object” Active as of 4/28/2021 object     Y
Supplement key value Indicates key value for Impact Based Warning string See https://ibm.co/3dlt7e7 tornado Y
Supplement value Indicates value for Impact Based Warning string See https://ibm.co/3dlt7e7 RADAR INDICATED Y

JSON Sample


{
             alertDetail:
             {
                      detailKey: "044ca89c-ad4d-3a7c-ac03-dca5882cb342",
                      messageTypeCode: 1,
                      messageType: "New",
                      productIdentifier: "MWS",
                      phenomena: "MA",
                      significance: "S",
                      eventTrackingNumber: "1",
                      officeCode: "KMFL",
                      officeName: "Miami",
                      officeAdminDistrict: "Florida",
                      officeAdminDistrictCode: "FL",
                      officeCountryCode: "US",
                      eventDescription: "Marine Weather Statement",
                      severityCode: 4,
                      severity: "Minor",
                      categories:
                      [
                                {
                                         category: "Met",
                                         categoryCode: 2,
                                }
                      ],
                      responseTypes:
                      [
                                {
                                         responseType: "Monitor",
                                         responseTypeCode: 6,
                                }
                      ],
                      urgency: "Expected",
                      urgencyCode: 2,
                      certainty: "Observed",
                      certaintyCode: 1,
                      effectiveTimeLocal: null,
                      effectiveTimeLocalTimeZone: null,
                      expireTimeLocal: "2021-10-04T16:30:00-04:00",
                      expireTimeLocalTimeZone: "EDT",
                      expireTimeUTC: 1633379400,
                      onsetTimeLocal: null,
                      onsetTimeLocalTimeZone: null,
                      flood: null,
                      areaTypeCode: "Z",
                      latitude: 26.59,
                      longitude: -79.37,
                      areaId: "AMZ670",
                      areaName: "Waters from Jupiter Inlet to Deerfield Beach FL from 20 to 60 NM",
                      ianaTimeZone: "America/New_York",
                      adminDistrictCode: "",
                      adminDistrict: null,
                      countryCode: "US",
                      countryName: "UNITED STATES OF AMERICA",
                      headlineText: "Marine Weather Statement until MON 4:30 PM EDT",
                      source: "National Weather Service",
                      disclaimer: null,
                      issueTimeLocal: "2021-10-04T15:35:00-04:00",
                      issueTimeLocalTimeZone: "EDT",
                      identifier: "7014b48832713fb8c8b9f0b932185abc",
                      processTimeUTC: 1633376123,
                      endTimeLocal: "2021-10-04T16:30:00-04:00",
                      endTimeLocalTimeZone: "EDT",
                      endTimeUTC: 1633379400,
                      texts:
                      [
                                {

                                         languageCode: "en-US",
                                         description: "...A STRONG THUNDERSTORM OVER THE OFF-SHORE PALM BEACH WATERS... The areas affected include... Waters
                                         from Lake Worth to Deerfield Beach FL from 20 to 60 NM... At 334 PM EDT, Doppler radar indicated a strong
                                         thunderstorm, capable of producing winds to around 30 knots. This thunderstorm was located 38 nm east of Highland
                                         Beach. The thunderstorm was nearly stationary. PRECAUTIONARY/PREPAREDNESS ACTIONS... Mariners can expect gusty winds
                                         to around 30 knots and locally higher waves. Boaters should seek safe harbor immediately until this storm passes.
                                         Waterspouts are possible with this activity. Remain on the alert in case warnings are issued for waterspout
                                         development. Dense fog was reducing visibilities to below 1 mile. Reduce your speed, and keep a lookout for other
                                         vessels, buoys, and breakwaters. Keep your navigation lights on. If not equipped with radar, you should consider
                                         seeking safe harbor. && ",
                                         instruction: null,
                                         overview: null,
                                }
                      ],
                      polygon:
                      [
                                {
                                         lat: 26.32,
                                         lon: -79.22,
                                },
                                {
                                         lat: 26.18,
                                         lon: -79.27,
                                },
                                {
                                         lat: 26.24,

                                         lon: -79.62,
                                },
                                {
                                         lat: 26.38,
                                         lon: -79.57,
                                },
                                {
                                         lat: 26.46,
                                         lon: -79.42,
                                },
                                {
                                         lat: 26.32,
                                         lon: -79.22,
                                },

                      ]
                      synopsis: null,
                      supplement: null,
             }
}
    "adminDistrict": "Texas",
    "countryCode": "US",
    "countryName": "UNITED STATES OF AMERICA",
    "headlineText": "River Flood Warning until 8AM CST MON",
    "source": "National Weather Service",
    "disclaimer": null,
    "issueTimeLocal": "2016-12-09T08:21:00-06:00",
    "issueTimeLocalTimeZone": "CST",
    "identifier": "949798b53e012bd0ace79a438d27a690",
    "processTimeUTC": 1481293269,
    "texts": [
      { 
             "languageCode": "en-US",
             "description": "...Flood Warning extended until Monday morning...The Flood Warning\ncontinues for the Guadalupe River Near Bloomington.\n* until Monday morning...or until the warning is                                     
cancelled.\n* At 8:00 AM Friday the stage was 25.2 feet.\n* Moderate flooding is occurring and Moderate flooding is forecast.\n* Flood stage is 20.0 feet.\n* Forecast: The river has crested overnight and will
continue to fall\nand is expected to go below flood stage by Sunday afternoon.\n* At 26.0 feet Irrigation and oil well pumps, tank batteries, and\nequipment in the lower flood plain below Victoria flood.
Livestock\nare cut off, may have to be fed by boat, and could drown. Homes\ndownstream above Highway 35 on the left bank are cut off.\n\n&&\n\nBelow are the latest river stages and stage forecasts:\n\nFLD
LATEST FORECAST 6 AM LST\nLOCATION STG STG DAY TIME Sat Sun Mon Tue Wed\n\nGuadalupe River\nBloomington 20 25.2 Fri 08 AM 23.8 21.1 18.7 17.8
17.6\n\n&&\n\n\n",
             "instruction": null,
             "overview": "...The Flood Warning continues for the following river in Texas...\n\nGuadalupe River Near Bloomington affecting Calhoun...Refugio and\nVictoria Counties\n\n.Recent rainfall upstream
and over the area will keep the aforementioned\nriver above flood stage for the next few days.\n\nPRECAUTIONARY/PREPAREDNESS ACTIONS...\n\nStay tuned to NOAA Weather Radio, local TV and
radio\nstations, or cable TV outlets, for the latest weather\ninformation, as additional rainfall could affect crest\nforecasts.\n\nFor the latest river stages and forecasts visit our AHPS page
at:\nhttp://water.weather.gov/ahps2/index.php?wfo=crp\n\n&&\n\n"
      }
   ],
   "polygon": [
      {
        "lat": 28.69,
        "lon": -97.04
      },
      {
        "lat": 28.69,
        "lon": -96.98
      },
      {
        "lat": 28.67,
        "lon": -96.95
      },
      {
        "lat": 28.57,
        "lon": -96.88
      },
      {
        "lat": 28.45,
        "lon": -96.8
      },
      {
        "lat": 28.43,
        "lon": -96.85
      },
      {
        "lat": 28.69,
        "lon": -97.04
      }
      ],
        "synopsis": null
   }
}

Significance Codes

Code Description
A Watch
B Bulletin
L Local Alerts
M Message
O Outlook
R Report
S Statement
W Warning
Y Advisory

JMA Significance Codes

Code Description
Y Advisory
W Warning
E Extreme

Alerts Event, Phenomena, Significance, & Threat Levels - See Weather Alerts - Headlines- v3

https://ibm.co/v3WAHa*Note: Aggregate Product Name only works for this API if used in conjuction with an API that makes active use of TWC Location Services

Tsunami Zones Exceptions:

Tsunami warnings are issued by Joint Australian Tsunami Warning Centre (JATWC) for Australian coastal locations and offshore territories. It also issues warnings for Antarctica. Below are some of the locations for which country code is not Australia for which JATWC issues tsunami warnings.

Islands in Australia:

These have a different ISO code than mainland Australia. It should be noted that when using “Alerts By Country” API and using code as “AU” will not return alerts for these islands.

Zone ID Zone Name Zone Type ISO Country Code Geocode
CC_TW001 Cocos Island Tsunami CC -12.1131, 96.8830
CX_TW001 Christmas Island Tsunami CX -10.4132, 105.6670
NF_TW001 Norfolk Island Tsunami NF -29.0624, 167.9330
NSW_PT245 Norfolk Island PointPlaces NF -29.0389, 167.9408

Antarctica:

For these locations, Location Master will not resolve the geocode to any location. There are no mappings defined for these geocodes and therefore “Alerts By Geocode” will not return any data for these locations. Alerts will return data for these locations when using “Alerts By Country” and “Alerts By Area”.

Zone ID Zone Name Zone Type ISO Country Code Geocode
AQ_TW001 Antarctica Tsunami AQ -67.6012, 62.8752
AQ_TW002 Antarctica Tsunami AQ -66.2820, 110.5230
AQ_TW003 Antarctica Tsunami AQ -68.5769, 77.9671

Alert Event, Phenomena, Significance, & Threat Levels

For a listing of of Event, Phenomena, Significance and Threat Levels see the document API - Standard - Weather Company Data - Core - v3 - Alerts - Weather Alerts - Headlines