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 November 1, 2016, NWS will implement the next version of the Forecast pages. Highlights will include a standardize look and feel, a mobile-ready landing page to select a location, and a competely new architecture with a modernized API. Please review the Service Change Notice for complete details.

Use the links below to preview special conditions:
Hide details

Documentation

Effective March 7, 2017, NWS will implement the next version of the Forecast pages. Highlights will include a standardize look and feel, a mobile-ready landing page, and a competely new architecture with a modernized API. Please review the Service Change Notice for complete details.

General Questions

Why are you updating the Forecast application?

With the new site release, the Forecast application was rewritten to modernize the architecture, remove duplication of services, and provide a service-oriented data structure or API. Developers will need to update their application to reflect the new API. 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 how it functions and not the experience. The path and parameters will change, and this will break bookmarks to the current version (for Forecast bookmarks, a link will guide you to the new location). Users can now select a location on a mobile device, and the hourly weather was moved over from the mobile site.

What happend 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 evironment friendly to print.

What happened to the "text-only" forecast?

A common use of the current "text-only" forecast was for low-bandwidth users. This also meant low-bandwidth users missed out on basic navigation and other information. Rather than completely eliminate the information, the new version of Forecast 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 put the forecast on my web page?

Yes, and you can customize the presentation for this request using the "mode" parameter. There two modes: min and widget. The "min" mode will only display the basic components: header, navigation, observation, forecast and detailed forecast. The "widget" mode goes further and removes the header/foorter—a common request when using an HTML iframe. For example: https://forecast-v3.weather.gov/point/38.9588,-94.624?mode=min. A future version of Forecast 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 web site. For example, A commonly used header called "UserAgent" tells a web site what type of device you are using so it can tailor the best experirence for you. No private information is shared in a header, and this is a standard pratice 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 provied 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, specially HTTP2, will make this design more efficient than a catch-all approach.

URL Mapping

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 Old Link New link
forecast.weather.gov/obslocal.php Old Link New link
forecast.weather.gov/zipcity.php Old Link New link
w1.weather.gov/data/obhistory/XXX.html Old Link New link
forecast.weather.gov/product_types.php Old Link New link
forecast.weather.gov/product_sites.php?site=YYY&product=ZZZ Old Link New link
forecast.weather.gov/product.php?site=YYY&product=ZZZ&issuedby=XXX Old Link New link
w1.weather.gov/glossary/index.php Old Link New link
w1.weather.gov/xml/current_obs/seek.php Old Link New link
w1.weather.gov/xml/current_obs/seek.php?state=fl Old Link New link
w1.weather.gov/xml/current_obs/display.php Old Link New link

Deprecated Pages

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 and never really used.

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
/gridpoint_spa.php All spanish specific pages will be removed
/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
/obslocal_spa.php All spanish specific pages will be removed
/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.
/MapClick_spa.php All spanish specific pages will be removed
/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 into your applications. This new design is a significant change and will be easier to navigate and discover the data to enrich your application. The new API is now separate from the Forecast web site. The new web site will only return HTML for viewing within a browser. Additional security measures will be implemented to prevent improperly using the web site to ingest forecast data. The new web site 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" header 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 (web site 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 endpoint on preview is:
https://api-v1.weather.gov

The API endpoint on production will be:
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 specifications:

  • GeoJSON: application/geo+json
  • JSON-LD: application/ld+json
  • DWML: application/vnd.noaa.dwml+xml
  • OXML: application/vnd.noaa.obs+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/location/{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/location/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

/alerts?{parameters} JSON-LD (default)

A list of alerts that can be filtered by parameters. If no parameters are provided, then all alerts are returned.

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)

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.

Values

none

Example

/alerts/active

/alerts/{alertId} JSON-LD (default)

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)

A list of active alerts by zone id.

Values

  • zoneId: a valid zone, see list in counts endpoint

Example

/alerts/active/zone/ILZ081

/alerts/active/area/{area} JSON-LD (default)

A list of active alerts by area.

Values

  • area: a valid area, see list in counts endpoint

Example

/alerts/active/area/KS

/alerts/active/region/{region} JSON-LD (default)

A list of active alerts by region.

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.