National Weather Service United States Department of Commerce

Extreme HeatRisk and Severe Weather Concerns

Major to Extreme HeatRisk continues for parts of the Mississippi Valley, mid-Atlantic and Northeast today. Additional heat concerns are increasing for the Pacific Northwest this week. Meanwhile, a cold front continues to track southward across the center of the nation. This will focus more showers and thunderstorms, some severe alongside excessive rainfall, from the Plains to the East Coast. Read More >

Upcoming Changes Effective June 20th, 2024
SCN 24-55: Upgrade NWS API Website Forecast and Alerts Endpoints

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

Pricing

All of the information presented via the API is intended to be open data, free to use for any purpose. As a public service of the United States Government, we do not charge any fees for the usage of this service, although there are reasonable rate limits in place to prevent abuse and help ensure that everyone has access. The rate limit is not public information, but allows a generous amount for typical use. If the rate limit is execeed a request will return with an error, and may be retried after the limit clears (typically within 5 seconds). Proxies are more likely to reach the limit, whereas requests directly from clients are not likely.

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" and "Specification" tabs 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-Flags: 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 ADASDM.

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.

Forecasts are created at each NWS Weather Forecast Office (WFO) on their own grid definition, at a resolution of about 2.5km x 2.5km. The API endpoint for the 12h forecast periods at a specific grid location is formatted as:

	https://api.weather.gov/gridpoints/{office}/{gridX},{gridY}/forecast

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

To obtain the grid forecast for a point location, use the /points endpoint to retrieve the current grid forecast endpoint by coordinates:

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

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

This will provide the grid forecast endpoints for three format options in these properties:

  • forecast - forecast for 12h periods over the next seven days
  • forecastHourly - forecast for hourly periods over the next seven days
  • forecastGridData - raw forecast data over the next seven days

Note: at this time coastal marine grid forecasts are only available from the forecastGridData property.

Applications may cache the grid for a location to improve latency and reduce the additional lookup request; however, it is important to note that while it generally does not occur often, the gridX and gridY values (and even the office) for a given coordinate may occasionally change. For this reason, it is necessary to check back to the /points endpoint periodically for the latest office/grid mapping.

The /points endpoint also contains information about the issuing office, observation stations, and zones for a given point location.

The forecast can be formatted as DWML for the /forecast and /forecast/hourly endpoints. There is no DWML specification for point lookups, so you first need to use the JSON-only /point endpoint described in the previous question to convert the location to a grid. Once you know the full gridpoint url for the forecast or hourly forecast, you can set the Accept header described in the overview to request the DWML format.

  • application/vnd.noaa.dwml+xml

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

Note! Please see below for current issues with the DWML format.

The following are missing from the /forecast endpoint

  • The conditions-icon > icon-link URL will point to the icon provided by the API
  • The parameters > temperature for type "heat index"

The following changes are new from the previous MapClick Point Forecast DWML

  • The XML header specifying the XML version and encoding
  • The location > height node includes attribute for "unit"
  • The location > description node will always be location > area-description
  • The wordedForecast node attribute for "wordGenerator" has an updated value

The API /forecast/hourly endpoint incorrectly returns the 12-hour Forecast DWML in the Hourly Forecast DWML structure. It cannot effectively be used to obtain hourly weather data.

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 above for all the filter options. For important details about filtered alerts requests according to county or zone UGC, please review our Alerts Geolocation Guide.

For additional details on the format of an alert's content, please see the CAP documentation.

The /alerts endpoint contains alerts issued over the past seven days. For an official archive of NWS CAP alerts, please reach out to the National Centers for Environmental Information (NCEI).

Updates

The information on this page is updated regularly. All official NWS Service Change Notices, including an email subscription option, can be found at weather.gov/notification.

Feature Flags

Feature flags are endpoint specific. See Specification tab for details.

/gridpoints/{wfo}/{x},{y}/forecast and /gridpoints/{wfo}/{x},{y}/forecast/hourly

  • forecast_temperature_qv: Represent temperature as QuantitativeValue
  • forecast_wind_speed_qv: Represent wind speed as QuantitativeValue

Known Issues

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

  • There is a bug that causes outages of forecast from the API when forecasts cross into a different year. This will be fixed before the end of 2024.
  • The gridpoints endpoint returns a 500 error. Retrying the request generally returns valid data.
  • The observations endpoints always show missing (null) wind gust and may show null values for other weather properties (temperature, wind, precipitation, etc.) at stations when the MADIS source has data.
  • Precipitation values in the observations endpoints are rounded down to the nearest centimeter (less than 0.4" may be improperly rounded down to 0).
  • /alerts/types shows "Evacuation - Immediate" but should be "Evacuation Immediate".

Updated 6/21/2024

Upstream Issues/Changes

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.

Resolutions

The following issues have been recently resolved:

  • 25 Feb 2022: The gridpoints endpoint no longer serves stale data. For this endpoint we currently are not returning the Last-Modified header. In addition, the If-Modified-Since header is also being ignored for gridpoints request.
  • 5 Jul 2022: Observations are again being sorted in chronological order.
  • 16 Mar 2023: The points endpoint no longer returns gridpoints URLs that are off by +1,+1.
  • 7 Nov 2023: The gridpoints endpoint no longer return a 503 error for long periods with forecasts for ABQ, LSX, MAF, TSA, and UNR.
  • 4 Jan 2024: The active alerts endpoint is now using the CAP 1.2 expiredReferences field to properly track alert history so that old alerts do not reappear in the endpoint.
  • 20 Jun 2024:
    • The gridpoints/forecast and gridpoints/forecast/hourly endpoints now work for WFO AFC (site id AER and ALU on the gridpoints endpoint).
    • Forecast endpoints no longer return a bad icons link when PoP = 0%.
    • The points endpoint now returns the correct grid values for locations within the WFO Anchorage public zones added in September 2023: AKZ102 Anchorage, AKZ103 East Turnagain Arm, AKZ112 Matanuska Valley, AKZ126 Western Prince William Sound, AKZ132 Northeast Prince William Sound, AKZ142 Copper River Basin.
  • 9 July 2024: The icon urls have been corrected to return the full url.

Specification

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