Welcome to the New NWS' Forecast!
Most changes are behind the scenes, but click here for differences you might notice.

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.

New Version 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 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 question "Can I embed the forecast on my web page" 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.

Will the web site work on my mobile device?

The web site was designed to replace mobile.weather.gov, and uses a responsive design that displays well on any device. Key features of the mobile site were transferred to the new version, including a mobile-friendly search page and the hourly forecast.

What happened to the link to the Spanish forecast?

The link is now named "Pronostico en Espanol" and is located in the "Additional Forecasts and Information" section on the forecast page.

What happened to the "Share" link to social media?

The "Share" social media links and icons were removed because of technical concerns. This feature will be revisited soon.

Where did the red, "Hazardous Weather Conditions" box on the forecast page go?

All warnings are now contained within the extended forecast section on the forecast page, and are limited to the NWS watches, warnings, advisories, and other similar products in the Common Alerting Protocol (CAP) version 1.2. Please refer to the CAP 1.2 service change notice for more details.

What if I experience an issue with the web site?

Please review the "Known Issues" tab on this page and contact us if the problem is not already identified.

General Functionality Questions

How do I print the 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.

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.

Why is the zone page showing on the forecast page?

The forecast will redirect to a zone page when there was is a technical issue with the forecast page, indicated by a blue banner with the message, "The zone data will be displayed until your location has been refreshed." This condition can occur when the forecast page cannot process the data provided by the field office or the data has expired. The field offices work quickly to issue updated data, and you do not need to submit a support ticket unless you experience this issue for a prolonged period of time.

Why is the forecast not using the closest observation station?

If the closest observation station does not have a current observation then the forecast page will use the next closest observation station. The list of observations stations is determined by the field office responsible for the forecast. Please use the contact information in the footer of the forecast page to contact the field office concerning observation issues.

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.

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

Known Issues

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

  1. Forecast page incorrectly displays a hazard condition (also known as an alert) that was updated or corrected.
    When a the status of a hazard condition is updated the API might be delayed in reflecting the status change on the forecast page. This is a known issue with the alert data sent by the NWS Telecommunications Operations Center, and will be resolved in a future update.
    [Tracking code: 847]

  2. The forecast hourly weather graph and hourly weather table does not provide bookmarking to retain selected options.
    This feature will be added to the web site on a future update.
    [Tracking code: 826]

  3. The forecast page does not redirect locations in Canada to Environment Canada's weather site.
    The forecast page now displays a user-friendly error page indicating the location is not within the the NWS boundaries. The redirect will be revisited for a future update.
    [Tracking code: 896]

  4. Older versions of Firefox may have presentation inconsistancies.
    Specific examples include the display of the time (e.g. "NOW until...") for hazard shading on conditions currently in affect, and the forecast page mini map might retain the view of the entire US versus automatically zooming to the appropriate point or zone.
    [Tracking code: 896]

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