National Weather Service United States Department of Commerce

Dangerous Heat Wave To Persist From The Midwest to the Ohio Valley

A very hot and humid air mass will persist today across much of the Midwest and Ohio Valley. Afternoon high temperatures will exceed 95 degrees in many locations with heat index values between 100 and 110. Hot temperatures will expand into the eastern U.S. on Monday with several of the major I-95 cities reaching 90 degrees or higher. Take it slow, drink plenty of fluids and limit outdoor exposure. Read More >

NWS has implemented the next version of the forecast pages. Highlights include a standardized look and feel, a mobile-ready landing page, and a completely new architecture with a modernized API. Please review the Service Change Notice for complete details.

API Use 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.

What's New?

Everything!

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

  2. Alerts fail to display on active endpoint

    The API is incorrectly calculating the expiration on VTEC-based alerts. This will cause the product to not return if the VTEC expiration is longer than the product expiration.

    Updated 06/08/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. HQ is aware of this issue and is investigating.

    Updated 06/08/2018

  2. HCE does not create air quality alerts

    HazCollect Extended (HCE) creates the CAP products that are provided by the API /alerts endpoints. HCE has a known issue with their feed for AQA, and therefore does not issue AQA warnings to be returned on the API. This is scheduled to be fixed July 10, 2018.

    Updated 06/08/2018

API Reference

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
Endpoint Formats Details
/gridpoints/{wfo}/{x},{y} GeoJSON (default)
JSON-LD

Raw (commonly referred to as "gridded") data provided by the Weather Office. Every forecast request will use this data to build the forecast response. The grid for a given location is determined by the "property.forecastGridData" property in the /points/{lat},{lon} endpoint.

Values

Example

/gridpoints/EAX/40,48

/points/{point} GeoJSON (default)
JSON-LD

Metadata about a point. This is the primary endpoint for forecast information for a location. It contains linked data for the forecast, the hourly forecast, observation and other information.

Values

  • point: EPSG:4326 latitude, EPSG:4326 longitude

Example

/points/39.0693,-94.6716

/points/{point}/forecast GeoJSON (default)
JSON-LD
DWML

Forecast data for a point. The DWML format is a temporary format to aid transition and will be sunset at a later date. This response is derrived from the /gridpoints endpoint and is intentionally less structured. If more structure is required, developers should use the /gridpoints endpoint directly.

Values

  • point: EPSG:4326 latitude, EPSG:4326 longitude

Example

/points/39.0693,-94.6716/forecast

/points/{point}/forecast/hourly GeoJSON (default)
JSON-LD

Hourly forecast data for a point. This response is derrived from the /gridpoints endpoint and is intentionally less structured. If more structure is required, developers should use the /gridpoints endpoint directly.

Values

  • point: EPSG:4326 latitude, EPSG:4326 longitude

Example

/points/39.0693,-94.6716/forecast/hourly

/points/{point}/stations GeoJSON (default)
JSON-LD

Stations nearest to a point in order of distance.

Values

  • point: EPSG:4326 latitude, EPSG:4326 longitude

Example

/points/39.0693,-94.6716/stations

/stations GeoJSON (default)
JSON-LD

A list of stations and station metadata that can be filtered by parameters. If no parameters are provided, then all stations are returned. This list is not configured by field offices and only returns active stations.

Values

none

Parameters

  • id, Station Id (comma-separated list of station ids)
  • state, State code (comma-separated list of US state abbreviations)
  • limit, Limit (an integer)

Example

/stations?limit=10 states=KS,MO

/stations/{stationId} GeoJSON (default)
JSON-LD

Metadata about a station. Similar to /stations endpoint with id parameter.

Values

  • stationId: the id of a station from the /points/{point}/stations endpoint

Example

/stations/KMKC

/stations/{stationId}/observations GeoJSON (default)
JSON-LD

A list of observations for a station.

NOTE! The API uses MADIS to provide observation data. The observation may be delayed while MADIS completes quality checks of the data. To limit the delay, the API is provided with incremental updates with various levels of checked data, and the API will return the variation of the observation with the most checked data. It is possible that no data is provided on the first variation, or that no data is checked on the first variation. It is up to the consumer to determine if the quality of data is appropriate. If not, the previous observation can be requested, or the next nearest station can be used. The API returns the state of the data for each value in the response, where "Z" (or "null") is for not checked (and may never be for some values) and "V" for checked. Please refer to MADIS for complete documentation on their data quality process.

Values

  • stationId: a valid station id (e.g. as provided by the /points/{point}/stations endpoint)

Parameters

  • start, Start time (ISO8601DateTime)
  • end, End time (ISO8601DateTime)
  • limit, Limit (an integer)

Example

/stations/KMKC/observations

/stations/{stationId}/observations/current GeoJSON (default)
JSON-LD
OXML

The most current observation for a station. Due to a legacy requirement, this endpoint will support XML for the near future when using the Accept header. It is highly recommend that applications update to the JSON format.

NOTE! See note in /stations/{stationId}/observations for important details on observation data.

Values

  • stationId: Station Id (e.g. as provided by the /points/{point}/stations endpoint)

Example

/stations/KMKC/observations/current

/stations/{stationId}/observations/{recordId} GeoJSON (default)
JSON-LD

Data for a specific observation.

NOTE! See note in /stations/{stationId}/observations for important details on observation data.

Values

  • stationsId: Station id
  • recordId, Record Id (ISO8601DateTime)

Example

/stations/KMKC/observations/2017-01-04T18:54:00+00:00

/products/{productId} JSON-LD

Data of a product.

Values

  • productId: an id provided by from another /product endpoint

Example

/product/NWS-IDP-PROD-2202326-2064512 (this id is likely now an expired product)

/products/types JSON-LD

A list of product types with an active product

Values

none

Example

/products/types

/products/types/{typeId} JSON-LD

A list of producuts by type.

Values

  • typeId: an id of a valid product type

Example

/products/types/AFD

/products/types/{typeId}/locations JSON-LD

A list of locations that have issues products for a type.

Values

  • typeId: an id of a valid product type (list forthcoming)

Example

/products/types/AFD/locations

/products/types/{typeId}/locations/{locationId} JSON-LD

A product for a location that has issued a product for a specific type.

Values

  • typeId: an id of a valid product type
  • locationId: an id of a valid location (list forthcoming)

Example

/products/types/AFD/locations/EAX

/products/locations JSON-LD

A list of locations with active products.

Values

none

Example

/products/locations

/products/locations/{locationId}/types JSON-LD

A list of active products by type for a specific location.

Values

  • locationId: an id of a valid location

Example

/products/locations/EAX/types

/offices/{officeId} JSON-LD

Metadata about a Weather Office.

Values

Example

/offices/EAX

/zones/{type}/{zoneId} GeoJSON (default)
JSON-LD

Metadata for a zone.

Values

  • type: a valid zone type (list forthcoming)
  • zoneId: a zone id (list forthcoming)

Example

/zones/forecast/MOZ028

/zones/{type}/{zoneId}/forecast GeoJSON (default)
JSON-LD

Forecast data for zone.

Values

  • type: a valid zone type (list forthcoming)
  • zoneId: a zone id (list forthcoming)

Example

/zones/forecast/MOZ028/forecast

/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)
  • area, 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

Format Preview

This tab allows you to to preview formats provided for API application development. For example, the KML and XML forecast buttons on a /point 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.