Using the API

How can I get NWS alerts for redistribution and use in decision support tools?

The alerts web service provides an Application Programming Interface (API) to distribute NWS watches, warnings, advisories, and other similar products. The default format of the API uses JavaScript Object Notation for Linked Data (JSON-LD) for both indexes and products. Products may also be retrieved in the original Common Alerting Protocol (CAP) v1.2 format and indexes in the Atom syndication format (ATOM).

What is JSON-LD?

JavaScript Object Notation for Linked Data is a method of encoding linked data using JSON. It is a lightweight format often used for REST web services and unstructured databases.

Where can I find the API specification for alerts?

Please refer to the API specification for endpoints that provide alert products and information.

How often can I request new alerts—what is the refresh rate?

We recommend you make requests of the server no more than every 30 seconds. Rate limiting firewalls are in place to prevent abuse and will automatically restrict access if limits are exceeded. This is to prevent abuse and ensure the service is accessible to all partners. If you have exceeded rate limits, simply wait until the rate limit window expires and attempt the request again. Refer to the API specification for more information on rate limits. Please contact sdb.support@noaa.gov for assistance.

What should I do if my access to alerts is blocked by the server?

If your access to alerts is blocked by the server, you probably exceeded the server’s pre-defined rate limits. Simply cease to make requests and access will be restored once the limit window has expired. Continued abuse may cause a permanent ban, and can only be resolved using the contact noted above.

What is ATOM?

ATOM is an XML based document format for syndicating news and other timely news-like information. The NWS ATOM feeds act as an index for active CAP messages by state, county, NWS forecast zones, as well as customizable indexes based on additional parameters to aid the automated dissemination of this information. ATOM provides headlines, URLs to the source document and brief description information in an easy to understand and use format. Software libraries exist to read the ATOM format and present ATOM headlines on webpages, personal computer workstations, and mobile devices. For consumers of these feeds as indexes to the CAP messages, the ATOM feeds contain several CAP data fields to assist in the tracking of available CAP messages with the goal of reducing the need to query the complete CAP message at every refresh.

Consumers of the CAP v1.2 feeds should use the ATOM index files to track active alerts in near real time and then pull the complete CAP messages as needed.

How do I navigate to NWS CAP from the ATOM feeds?

Consumers of CAP can leverage the API alert endpoints as an index to help find active CAP messages for a given state, county, or NWS forecast zone. Note that the index contains several alert data fields to assist in the tracking of available CAP messages with the goal of reducing the need to query the complete CAP message at every refresh.

To subscribe to an ATOM feed, select the ATOM icon Atom for a state. Alternatively, select the Zone List or County List link to select from a list of NWS forecast zones or counties, respectively. In many locations, the forecast zones roughly follow county lines. The resulting page is the ATOM feed of active alerts which includes links to the CAP messages for the respective area.

Using NWS CAP

How is NWS CAP used with traditional and emerging technologies?

NWS CAP can be used to launch Internet messages, trigger alerting systems, feed mobile device (e.g., cell phone/smart phone and tablet) applications, news feeds, television text captions, highway sign messages, and synthesized voice over automated telephone calls or radio broadcasts. CAP content, such as the urgency, severity, and certainty values make CAP particularly valuable for use in decision support tools.

NWS CAP must not be used to activate the Emergency Alert System (EAS)

While the NWS encourages third parties to redistribute our alerts in a multitude of applications and decision support tools, the NWS CAP messages MUST NOT be used as input into EAS encoder/decoder boxes to activate EAS until an announcement that NWS CAP is suitable for EAS service. Activation of EAS for NWS watches and warnings should only be done based on NOAA Weather Radio (NWR) Specific Area Message Encoding audio feed and on standard NWS text messages.

NWS CAP does not include all non-weather emergency alerts

FEMA IPAWS is intended to serve as this nation's emergency alert aggregator containing weather and non-weather emergency alerts from alerting authorities. These alerting authorities, such as NWS and many emergency management agencies, post directly to IPAWS. Thus, those seeking all-hazard alert information in CAP format should obtain it from IPAWS. However, some emergency management agencies still rely on NWS to generate non-weather emergency messages on their behalf and do not yet have the capability to push alerts to IPAWS. These alerts are available from this site and via other NWS dissemination systems.

Where can I find a geospatial representation of the geographic zones listed in NWS CAP messages?

Many NWS-produced alerts define the alert area by NWS forecast zone. NWS provides shapefiles where serve as a geospatial representation of these zones.

Additional Sources

What are additional sources for NWS CAP?

For the most reliable and resilient CAP service, obtaining NWS CAP alert messages from multiple sources is recommended. Note that these services only provide the alert producs in the CAP format.

• FEMA IPAWS is a good source to pull NWS CAP v1.2 alerts because both weather and non-weather alert messages are available from this single source. FEMA IPAWS requires application for access with FEMA. For more information, see FEMA IPAWS Internet Services. Software developers are encouraged to participate in regular FEMA IPAWS Practitioner and Developer webinars to learn how to get and use CAP alerts from IPAWS. Since NWS also pushes CAP v1.2 messages to the FEMA IPAWS, IPAWS serves as an excellent primary or backup source for NWS CAP v1.2 messages.
• NOAAPORT is the most robust push mechanism for receiving NWS CAP messages. The initial cost for NOAAPORT is highest among NWS CAP push services. For more information about NOAAPORT, please see http://www.nws.noaa.gov/noaaport/html/noaaport.shtml.
• NWWS is the second most robust push mechanism for receiving NWS CAP v1.2 messages. NWWS is available as a satellite-based and Internet-based service. For more information about NWWS, please see http://www.nws.noaa.gov/nwws/index.html.

What is the difference between push and pull?

Pulling alerts typically involves little or no cost. However, there is inherent delay because the alerts must be request at time intervals. NWS CAP is available via the following pull methods:

The major advantage of most push methods is timeliness. A frequently expressed disadvantage is a higher cost due to equipment and software resource needs. The results of the several months of experimental NWS CAP v1.2 push via NOAAPORT and NWWS shows CAP availability typically less than 45 seconds from creation with very high reliability. NWS push methods use discrete message or product identifiers called World Meteorological Organization (WMO) headings and Advanced Weather Interactive Processing System (AWIPS) identifiers.

Support

How can I contact NWS for CAP support?

To report real-time, operational CAP-related concerns, contact the NWS Telecommunications Center (TOC) at 301-713-0902 or email nco.ops@noaa.gov. For CAP program or general information questions, email mike.gerber@noaa.gov. For CAP technical or production questions, email sdb.support@noaa.gov.

Known Issues

Web Site

No issues.

API

Please refer to the "Issues/Changes" tab on the API page for issues that impact alert endpoints.

CAP

1. Alaska Region does not issue marine alerts in a manner that is processed by HCE, therefore the marine products are not included in CAP 1.2. The National Weather Service is investigating a resolution.

   Updated 01/11/2019

Change Log

Web Site

No changes.

API

No changes.

CAP

The following changes were completed December 12, 2017: 

1. Disables WEA for zone-based Dust Storm Warnings. Polygon-based Dust Storm Warnings will still activate WEA.
2. Implements dual ingest feed from both the satellite and a terrestrial link.
3. Reduces fail over times when moving applications between the data centers.
4. Corrects some invalid WEA polygons which were found during Hurricane Michael.
5. Supports the upcoming change to Guam products with the new PQ1 and PQ2 WMO identifiers.
6. Corrects the issue with timestamps in the CAP messages for Guam.
7. Corrects the decoding of polygons in Guam products to assign a latitude in the Eastern Hemisphere.
8. Corrects the <references> tag to include all prior messages in the series, with the exception of Flood Warnings which only reference the prior message due to the very long effective times and excessive number of references.
9. Properly assigns products with a "SPN" office identifier as being from San Juan.

The following changes were completed April 4, 2017:

1. Tsunami Warnings will now be properly parsed to create CAP messages.
2. HazCollect Extended core has been rewritten to more efficiently and accurately parse Universal Geographic Codes, including mixed UGCs found in Tsunami Warnings.
3. Precaution/Preparedness statements and headlines are now properly captured into the corresponding CAP tags.
4. River Flood Warnings are now parsed properly.
5. Added machine readable fields found in some convection warning products as new tags. These include storm motion, location, and time, hail size, wind gust potential, tornado potential, and tornado damage potential.
6. Support for Non-Weather Emergency Messages to be CAP formatted. These are not transmitted to IPAWS.
7. More accurate generation of FIPS and SAME codes for products with a UGC type of National Weather Service Public Zones.
8. Better capturing of the description tag for a variety of different product types.
9. More reasonable headlines, urgency, severity, and certainty for NWS products which are cancelled, expired, or upgraded.

The following changes were completed May 16, 2017:

1. CAP v1.2 Documentation updated to include documentation for the storm motion/location/time, hail size, wind gust potential, tornado potential, tornado damage potential, and NWSheadline parameters added on April 4, 2017.

CAP v1.2 is designed to be backward compatible with CAP v1.1. However, depending on how you parse and re-use data from NWS-produced CAP v1.1 messages in your services, you may need to make adjustments in order to seamlessly transition those services to use NWS-produced CAP v1.2. Please see the CAP v1.2 Transition Guide which identifies differences and improvements in content between the legacy NWS CAP v1.1 and CAP v1.2.

Why have things changed compared to the way I used to access CAP from the alerts website?

The web site will only display HTML structured data for viewing alerts within a web browser, while the API provides a service-oriented data structure that makes it easier for developers to build applications. The API also provides richer data sets through linked data to other resources. Developers who previously accessed NWS CAP v1.1 via the web will need to update their applications to send the proper http headers to retrieve either XML or JSON.

Examples

The following are examples of how the API provides alerts compared to the previous version. Please refer to the API specification for complete details and additional filter criteria only provided by the API.

• History of alerts

  Current: Not available

  New: https://api.weather.gov/alerts

• Active alerts

  Current: https://alerts.weather.gov/cap/us.php?x=0

  New: https://api.weather.gov/alerts/active

• Active alerts for a state (e.g. Missouri)

  Current: https://alerts.weather.gov/cap/mo.php?x=0

  New: https://api.weather.gov/alerts/active?area=MO

• Active alerts for a marine area (e.g. Lake Michigan)

  Current: https://alerts.weather.gov/cap/mzgl.php?x=0

  New: https://api.weather.gov/alerts/active?area=LM

• Active alerts for a point (e.g. lat: 39, lon: -90)

  Current: Not available

  New: https://api.weather.gov/alerts/active?point=39,-90

• Active alerts for a region (e.g. Atlantic)

  Current: https://alerts.weather.gov/cap/mzat.php?x=0

  New: https://api.weather.gov/alerts/active?region=AT

• Active alerts for a zone (e.g. Bibb, in Alabama)

  Current: https://alerts.weather.gov/cap/wwaatmget.php?x=ALZ034&y=0

  New: https://api.weather.gov/alerts/active?zone=ALZ034

• Active alerts for a county (e.g. Bibb, in Alabama)

  Current: https://alerts.weather.gov/cap/wwaatmget.php?x=ALC007&y=0

  New: https://api.weather.gov/alerts/active?zone=ALC007