National Weather Service United States Department of Commerce

Heavy to Excessive Rain for Southeast and Mid-Atlantic into this Weekend; High Winds in the Pacific Northwest Friday

Another southern storm system will bring heavy to excessive rainfall with a risk for severe thunderstorms from the central Gulf Coast to the Southeast Friday. This heavy rainfall will then spread across the Mid-Atlantic region late Friday into the Weekend. A strong cold front moving into the Pacific Northwest will bring strong, possibly damaging winds to the coast Friday. Read More >

Overview

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

Content Negotiation

The API will use Accept headers 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/vnd.noaa.dwml+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 (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.

Endpoints

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

Endpoints typically have a GeoJSON default format and additional formats may be requested using the request header. For example, to request DWML formatting for the point forecast at http://api.weather.gov/point/XXX,XXX/forecast, set the accept header to "application/vnd.noaa.dwml+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 references:

  • 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

General Questions

What is an Accept header?

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.

Why does the API require multiple requests for all the information?

There are many uses for the weather information provided by the API, and, historically, the service responded with everything but the kitchen sink. This design bloated bandwidth and make caching efforts difficult. One goal of the new API was a design that allowed repeat users of specific data the ability to access only the information needed. Another goal was to expire content based upon the information life cycle. The new approach using JSON-LD achieves both of these goals. While this requires additional requests, future enhancements, especially HTTP2, will make this design more efficient than a catch-all approach.

How do I discover weather data 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. The /points/location endpoint is the most common endpoint to discover additional API content given the popularity of weather data based upon a location (latitude and longitude).

For example, to discover the endpoint of the raw forecast, the application would first request:

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

 

This response tells the application where to find relative information–including office, zone and forecast data–for a given point. The application can then use the linked data in the previous response to locate the raw forecast:

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

 

If an application knows the office and grid position for a location (through caching—a similar concept to a bookmark for users), the link data would not be needed to locate the content for raw forecast data.

Known Issues

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

  1. Random, missing alerts

    An infrastructure issue is causing a small percentage of random alerts to fail to return on the API /alerts endpoints. This is being worked, and will likely take several weeks to resolve.

    Updated 09/05/2018

  2. Delayed observations

    An infrastructure issue is causing delayed processing of observation station data. Observations may be intermittently delayed or not available. This is being worked, and will likely take several weeks to resolve.

    Updated 09/05/2018


Upstream Issues

  1. 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 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 06/08/2018

 

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/*