Documentation

Effective May 2, 2017, NWS will implement the next version of the Alert pages. Highlights will include a standardize look and feel, a mobile-ready landing page, and a competely new architecture with a modernized API. Please review the Service Change Notice for complete details.

General Questions

What is the Alerts application?

The Alerts application provides access to NWS watches, warnings, advisories, and other similar products in the Common Alerting Protocol (CAP) and Atom Syndication Format (ATOM). Information below refers to CAP v1.2.

Why are you updating the Alerts application?

With the new site release, the Alerts application was rewritten to modernize the architecture, remove duplication of services, and provide a service-oriented data structure or API. Developers will need to update their application to reflect the new API. It has been improved to provide richer data sets through linked data to other resources. Please refer to the "API Reference" tab for more details.

How do I transition from CAP v1.1 to v1.2?

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.

How is ATOM and CAP used with traditional and emerging technologies?

NWS CAP and ATOM feeds 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.

What is CAP?

CAP is an XML-based information standard used to facilitate emergency information sharing and data exchange across local, state, tribal, national and non-governmental organizations of different professions that provide emergency response and management services. The NWS CAP messages on this page are produced in the CAP v1.2 format defined by the Organization for the Advancement of Structured Information Standards (OASIS) and conform to the CAP v1.2 USA Integrated Public Alert and Warning System (IPAWS) Profile Version 1.0.

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, and NWS forecast zones 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.

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

Consumers of CAP can leverage the ATOM feed as an index to help find active CAP messages for a given state, county, or NWS forecast zone. Note that each ATOM feed contains 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.

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.

What is the refresh rate?

The ATOM and CAP feeds are updated about every two minutes.

What are the recommended best-practices?

While some non-weather alerts may be available via this site, the site is not intended to serve as an all-hazards alert aggregator. FEMA IPAWS serves as this nation's emergency alert aggregator containing weather and non-weather emergency alerts. Those seeking all-hazard alert information in CAP format should obtain it from IPAWS.

For the most reliable and resilient CAP service, obtaining NWS CAP alert messages from multiple sources is recommended. 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.

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 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 TOC.NWSTG@noaa.gov. For CAP program or general information questions, email mike.gerber@noaa.gov. For technical CAP or production questions, email robert.bunge@noaa.gov.

Technical Notes about the NWS CAP v1.2 Messages.

  • NWS CAP v1.2 alerts are considered experimental at this time.
  • The online National Weather Service CAP v1.2 Documentation (coming soon) supplements the OASIS CAP v1.2 standard and CAP v1.2 USA Integrated Public Alert and Warning System (IPAWS) Profile Version 1.0 by identifying the formats of NWS information contained within NWS CAP v1.2 messages. A couple of new NWS parameters are possible before NWS CAP v1.2 becomes operational.
  • CAP v1.2 messages on NWS web pages and received via NWS push methods 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.
  • The ATOM indexes contain a number of CAP v1.2 fields as an extension to the ATOM fields. These fields are included to provide additional information to the consumer with the intent of reducing the need to pull the entire CAP message every time.
  • An XML style sheet is used to display the CAP message in a human readable format in modern web browsers. Not all CAP fields are displayed in the human view. Be sure to view the message source to see all available fields.
  • NWS provides shapefiles of NWS forecast zones that are provided in the UGC system and also parsed into fields in the CAP v1.2 messages.
  • For the most reliable and resilient CAP service, obtaining NWS CAP alert messages from multiple sources is recommended
  • The online National Weather Service CAP v1.2 Documentation supplements the OASIS CAP v1.2 standard and CAP v1.2 USA Integrated Public Alert and Warning System (IPAWS) Profile Version 1.0 by identifying the formats of NWS information contained within NWS CAP v1.2 messages. A couple of new NWS parameters are expected before NWS CAP v1.2 becomes operational.

Methods to get NWS CAP v1.2 Messages

***PULL***

The major advantage of the Atom feeds and the pull is that it is easy and inexpensive to implement with little or no resources. The disadvantage is the inherent delay introduced by a pull service like alerts.weather.gov. The NWS CAP v1.2 pull has been designed and engineered to reduce the delay as much as possible. It should be understood that it is only as fast as the client is configured to pull it - every 2, 5, 10, even 15 minutes - based on the consumer's own technical needs and constraints. It should be understood that some alerts (ex. Tornado Warnings) are extremely time sensitive.

NWS CAP v1.2 alerts are available via the following pull methods:

  • 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.

***PUSH***

The major advantage of most push methods is timeliness. 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. A frequently expressed disadvantage is a higher cost due to equipment and software resource needs.

NWS push methods use discrete message or product identifiers called World Meteorological Organization (WMO) headings and Advanced Weather Interactive Processing System (AWIPS) identifiers.

NWS CAP v1.2 alerts are currently via the following push methods:

  • NOAAPORT - NOAAPORT is the most robust mechanism for receiving NWS CAP v1.2 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/os/disemsys.shtml.
  • NWWS is the second most robust 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/os/disemsys.shtml.
  • Additional push methods coming soon.

API Reference

We are excited to announce a brand new API to provide Alerts data for your applications. This new design is a significant change and will be easier to navigate and discover the data to enrich your application. The new API is now separate from the Alerts web site. The new web site will only return HTML for viewing within a browser. Additional security measures will be implemented to prevent improperly using the web site to ingest forecast data. The new web site is now a lightweight presentation view that uses the same API to display alerts. This same data will be available to you through the API.

Content Negotiation
The API will use "Accept" header to modify the response returned. See the FAQ tab for more information. Parameters include:

  • Version of the API, defaults to the oldest
  • Format of the response, default in specifications
An example of the Accept header would be "Accept: application/atom+xml;version=1"

Authentication
A User Agent will still be required to identify your application. This string can be anything, and the more unique to your application the less likely it will be affected by a security event. If you include contact information (web site or email) we can contact you if your string is associated to a security event. This will be replaced with an API key in the future.

Endpoints
The API endpoint on preview is:
https://alerts-v2.weather.gov

The API endpoint on production will be:
https://alerts.weather.gov

Endpoints typically have a GeoJSON default format, and additional formats may be requested using the request header. For example, to request CAP formatting for an alert at http://api.weather.gov/alert/XXX set the accept header to "application/cap+xml." Use the reference below to determine what formats are available for each endpoint.

Here are the full string formats for the shorthand in the specifications:

  • GeoJSON: application/geo+json
  • JSON-LD: application/ld+json
  • CAP: application/cap+xml
  • ATOM: application/atom+xml

Endpoint Formats Details
/alerts?{parameters} JSON-LD (default)
ATOM

A list of alerts that can be filtered by parameters. If no parameters are provided, then all alerts are returned. The ATOM format returns items in CAP-ATOM.

Values

none

Parameters

  • active, Active alerts (1 or 0)
  • start, Start time (ISO8601DateTime)
  • end, End time (ISO8601DateTime)
  • status, Event status (alert, update, cancel)
  • type, Event type (list forthcoming)
  • zone_type, Zone type (land or marine)
  • point, Point (latitude,longitude)
  • region, Region code (list forthcoming)
  • state, State/marine code (list forthcoming)
  • zone, Zone Id (forecast or county, list forthcoming)
  • urgency, Urgency (expected, immediate)
  • severity, Severity (minor, moderate, severe)
  • certainty, Certainty (likely, observed)
  • limit, Limit (an integer)

Example

/alerts?active=1

/alerts/active JSON-LD (default)
ATOM

A list of active alerts that can be filtered by parameters. Uses same parameters as the /alerts endpoint, but sets "active" parameter to 1 and ignores "start" and "end" parameters. The ATOM format returns items in CAP-ATOM.

Values

none

Example

/alerts/active

/alerts/{alertId} JSON-LD (default)
CAP

A specific alert by id provided by a search or list.

Values

  • alertId: an active alert id provided by another endpoint

Example

/alerts/NWS-IDP-PROD-2202530-2064731

/alerts/active/count JSON-LD (default)

A list of active counts for regions, areas and zones. A list of these items forthcoming.

Values

none

Example

/alerts/active/count

/alerts/active/zone/{zoneId} JSON-LD (default)
ATOM

A list of active alerts by zone id. The ATOM format returns items in CAP-ATOM.

Values

  • zoneId: a valid zone, see list in counts endpoint

Example

/alerts/active/zone/ILZ081

/alerts/active/area/{area} JSON-LD (default)
ATOM

A list of active alerts by area. The ATOM format returns items in CAP-ATOM.

Values

  • area: a valid area, see list in counts endpoint

Example

/alerts/active/area/KS

/alerts/active/region/{region} JSON-LD (default)
ATOM

A list of active alerts by region. The ATOM format returns items in CAP-ATOM.

Values

  • area: a valid region, see list in counts endpoint

Example

/alerts/active/region/GL

Change Log

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.

Access to alerts may be blocked if you exceed server rate limits

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 your access to alerts is blocked by the server, you probably exceeded the server's pre-defined rate limits. To determine if you have exceeded rate limits or other security limits please contact nids.support@noaa.gov for assistance. If that does not resolve the problem, please contact the NWS Telecommunications Center (TOC) at 301-713-0902 or email TOC.NWSTG@noaa.gov.

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.

Format Preview

This tab allows you to to preview formats provided for API application development. For example, the ATOM button on the home page will link to this page with the output below. Visit the "API Reference" tab to learn how to make an API request using different formats.

This format preview is not operational and should not be used for support decisions.

No preview requested.