Preview of NWS' New Version of Forecast
This preview is not operational and should not be used for support decisions.
Click here for details.

Effective April 4, 2017, NWS will implement the next version of the forecast pages. Highlights will 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.

General Questions

Why are you updating the forecast pages?

With this update, the forecast pages have been rewritten to modernize the structure, remove duplications, and provide a service-oriented data structure or API. Developers using the NWS API will need to update their application to reflect the new version. 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.

What will change on the web site?

The user experience remains mostly the same, as the primary goal of this update is to provide more consistent service. The URLs of many pages will change, including all forecast pages, and this will break existing bookmarks that users may have. A link on the error message of the old page will guide users to the new location. Users can now select a location on a mobile device, and the hourly weather was added to the mobile site.

What happened to the printable forecast?

All pages are now designed to be print-friendly. Click the print button in your browser for a presentation that is environmentally friendly to print.

What happened to the text-only forecast?

The most common use of the current text-only forecast was by low-bandwidth users. This also meant low-bandwidth users missed out on basic navigation and other information. Rather than completely eliminating the information, the new version of the forecast pages will present the same information using a low-bandwidth display. The low-bandwidth display will now apply to all pages, not just the forecast.

Enable this presentation by setting the "view" parameter to: plain. For example: https://forecast-v3.weather.gov/point/38.9588,-94.624?view=plain. Also see the next question that will further reduce the overall page bandwidth, which would result in this example: https://forecast-v3.weather.gov/point/38.9588,-94.624?view=plain&mode=min. Note that this feature is still being optimized for best performance.

Can I embed the forecast on my web page?

Yes. You can also customize the appearance of this forecast using the mode parameter. There currently three modes: min, widget, and ext.

  • The min mode will only display the basic components: header, navigation, and detailed forecast.
  • The ext mode will display the header, navigation, and the extended forecast.
  • The widget mode will display the observation, extended forecast, and detailed forecast, but removes the header/footer(a common request when using an HTML iframe).

Example: https://forecast-v3.weather.gov/point/38.9588,-94.624?mode=min.

A future version of the forecast page will provide a JavaScript library that will place the forecast onto your site without an iframe.

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

Updated Links

This is a list of common URLs in both the new version (Preview) compared to the current version (Production). The current version URLs will not function once the new version is released.

Page Current Site (Production) New Site (Preview)
/MapClick.php?lat=XX.XX&lon=YY.YY Current Link New link
forecast.weather.gov/obslocal.php Current Link New link
forecast.weather.gov/zipcity.php Current Link New link
w1.weather.gov/data/obhistory/XXX.html Current Link New link
forecast.weather.gov/product_types.php Current Link New link
forecast.weather.gov/product_sites.php?site=YYY&product=ZZZ Current Link New link
forecast.weather.gov/product.php?site=YYY&product=ZZZ&issuedby=XXX Current Link New link
w1.weather.gov/glossary/index.php Current Link New link
w1.weather.gov/xml/current_obs/seek.php Current Link New link
w1.weather.gov/xml/current_obs/seek.php?state=fl Current Link New link
w1.weather.gov/xml/current_obs/display.php Current Link New link
/gridpoint_spa.php, /obslocal_spa.php, /MapClick_spa.php Multiple New link

Removed Links

The following pages have been removed from the Forecast application. They were either no longer needed because their functions were replaced by other pages or functions or they were experimental.

Page Description
/error_404.php The general 404 error page has been replaced with a new one.
/MkBackGround.php
/gridpoint.php An experimental page that rendered various data points on a localized map
/stations.php A legacy page that displayed a list of stations for a given area with
/index.php The legacy landing page that redirected to weather.gov
/showsigwx.php Legacy page that showed Warnings, Watches, and Advisories for a given area.
/common.php
/siteNews.php A backend page that pulled news stories from CMS for use on Forecast
/glossary.php This page will be recreated in a different format
/sitestatus.php
/status.php
/shmrn.php Legacy marine forecast page. Was replaced by MapClick marine page in Forecast version 2.
/product_sites.php List of sites with a particular Product (ie. AFD). Will be replaced by another page.
/preview.php Legacy forecast (version 1) page which was replaced with the WFO landing page in version 2
/gfestatus.php This page was moved to an internal URL
/gfestatuslite.php This page was moved to an internal URL
/netcdfheader.php This page was moved to an internal URL

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/{stationId} GeoJSON (default)
JSON-LD

Metadata about a station.

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.

Values

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

Example

/stations/KMKC/observations

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

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

Values

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

Example

/stations/KMKC/observations/current

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

Data for a single observation.

Values

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

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

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.