National Weather Service United States Department of Commerce

Severe Weather for the Central High Plains; Heavy Rain/Flood Concerns in Parts of the East

Strong to severe thunderstorms capable of strong winds and large hail are possible over portions of the central High Plains this afternoon, including parts of the Denver metro area. A stalled front is expected to bring additional rain and flash flood risks in the Mid-Atlantic and Southeast through Thursday. Red flag warnings are in effect across the Interior Northwest and Great Basin today. Read More >

Overview

The National Weather Service (NWS) API allows developers access to critical forecasts, alerts, and observations, along with other weather data. The API was designed with a cache-friendly approach that expires content based upon the information life cycle. The API is based upon of JSON-LD to prommote machine data discovery.

The API is located at: https://api.weather.gov

Operational issues should be reported to nco.ops@noaa.gov.

General use questions can be asked on the API github site.

Content Negotiation

The new API will use headers to modify the version and format of the response. Every request, either by browser or application, sends header information every time you visit any website. For example, a commonly used header called "UserAgent" tells a website what type of device you are using so it can tailor the best experience for you. No private information is shared in a header, and this is a standard practice for all government and private sites. Developers can override these headers for specific purposes (see the "API Specifications" tab for more information). You can get full details by visiting the header field definitions page at the World Wide Web Consortium site.

  • Authentication
  • Format the response
  • Request new features

Authentication

A User Agent is 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 (website 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.

User-Agent: (myweatherapp.com, contact@myweatherapp.com)

Formats

Endpoints typically have a GeoJSON default format, given the inclusion of geometry data. See the Specification tab for details on each endpoint. Below are common formats available by the API.

  • GeoJSON: application/geo+json
  • JSON-LD: application/ld+json
  • DWML: application/vnd.noaa.dwml+xml
  • OXML: application/vnd.noaa.obs+xml
  • CAP: application/cap+xml
  • ATOM: application/atom+xml
Accept: application/cap+xml

Features

The API will use feature flags to make new features available to consumers. The available feature flags will be noted on the "Updates" tab on this page. The feature flag will be communicated through a Service Change Notice (SCN) allowing developers a period to adopt the flag if the change impacts their applications. Once the adoption window expires, the feature will be made default. Developers can then remove the flag at their convenience.

Feature-Flag: forecast_temperature_qv

Outage Information

Information on outages is generally communicated through Administrative messages sent by National Center of Environmental Prediction's (NCEP's) Senior Duty Meteorologist (SDM). These are sent via WMO id NOUS42 KWNO and product identifier ADMNFD. On 30 April 2020, these will be sent via a new product id, ADANFD. Please see SCN 20-39 at the below link for more information.

https://www.weather.gov/media/notification/scn20-39sdm_admin_messages.pdf

Examples of using the API

The API uses linked data to allow applications to discover content. Similar to a web site that provides HTML links to help users navigate to each page, linked data helps applications navigate to each endpoint. You may also review the OPEN API specification on the "Specification" tab on this page, or directly using the specification endpoint (that is also used to create the tab presentation): https://api.weather.gov/openapi.json.

How do I get the forecast?

Forecasts are divided into 2.5km grids. Each NWS office is responsible for a section of the grid. The API endpoint for the forecast at a specific grid is:

https://api.weather.gov/gridpoints/{office}/{grid X},{grid Y}/forecast

For example: https://api.weather.gov/gridpoints/TOP/31,80/forecast

If you do not know the grid that correlates to your location, you can use the /points endpoint to retrieve the exact grid endpoint by coordinates:

https://api.weather.gov/points/{latitude},{longitude}

For example: https://api.weather.gov/points/39.7456,-97.0892

This will return the grid endpoint in the "forecast" property. Applications may cache the grid for a location to improve latency and reduce the additional lookup request. This endpoint also tells the application where to find information for issuing office, observation stations, and zones.

How do I get alerts?

The API has a robust selection of filters for alerts. A common request is all active alerts for a state:

https://api.weather.gov/alerts/active?area={state}

For example: https://api.weather.gov/alerts/active?area=KS

The /alerts/active endpoint redirects internally to the root /alerts endpoint with the "active=true" parameter. Please review the "Specification" tab for all the filter options.

Updates

The information on this page is updated regularly.

Feature Flags

There are currently no feature flags.

Known Issues

Before contacting us, please review the following list of issues that have been identified for a future update.

  • Delayed observations

    Observations processing of observation station data has a performance constraint. Observations may be delayed up to five minutes. The resolution does not have a deploy date.

    Updated 03/11/2020

Upstream Issues

The following issues are related to upstream sources of the API, and are not an API bug.

  • Delayed observations

    Observations may be delayed up to 20 minutes from MADIS, the upstream source.

    Updated 03/11/2020

  • HCE does not provide Alaska Region marine products

    HazCollect Extended (HCE) creates the CAP products that are provided by the API /alerts endpoints. Alaska Region does not issue marine alerts in a manner that is processed by HCE, therefore the marine products are not returned on the API. The National Weather Service is investigating a resolution.

    Updated 03/11/2020

Resolutions

The following issues have been recently resolved.

  • There are no recently resolved issues to report

Specification

Important! Only the following endpoints are considered operational. Changes to operational endpoints are subject to PNS and SCN notices. All other endpoints are subject to change without notice.

  • /alerts/*

Note: All times generated by the API are in ISO-8601 format.