982
NOUS41 KWBC 151550
PNSWSH

Service Change Notice 24-50
National Weather Service Headquarters Silver Spring MD
1150 AM EDT Wed May 15 2024

To: Subscribers:
 -NOAA Weather Wire Service
 -Emergency Managers Weather Information Network
 -NOAAPort
 Other NWS Partners, Users and Employees

From: George Jungbluth
 Director, Office of Dissemination

Subject: Migration of JSON and DWML Data Services to NWSs API
Application
 at api.weather.gov and Removal from forecast.weather.gov,
 Effective June 27, 2024

On or about June 27, 2024, at 1200 UTC, the National Centers for
Environmental Prediction (NCEP) Central Operations (NCO) will
terminate
the digitalDWML and digitalJSON data services on the Forecast
application
at forecast.weather.gov. The same data is available in a similar
format
from the NWSs Application Programming Interface (API) application
at
api.weather.gov. In the event of a Critical Weather Day (CWD) or an
Enhanced Caution Event (ECE), any changes will proceed within 5
business
days after expiration. Users can find CWD/ECE status at the link
below and
should monitor the weather.gov website headline for updated
notifications.
https://www.nco.ncep.noaa.gov/status/cwd/

To better support the public, the NWS is committed to improving
services
across all of its domains. As part of this effort, the Office of
Dissemination (DIS) is working with NCO to update dissemination
applications for security, reliability and utility, and as well as
minimize duplication of efforts across multiple platforms.

Weather.gov is moving to new, secure hosting infrastructure within
the NWS
Integrated Dissemination Program, requiring redevelopment of much of
the
base code. As this transition occurs, NWS will be discontinuing the
DWML
and JSON format forecast that is available via the Forecast
application at
forecast.weather.gov in favor of the same data also on the API
application
at api.weather.gov. The mechanism to retrieve it and the differences
in
output will require updates from users to enable a full switch
between the
two applications.

The full documentation for the NWSs API application at
api.weather.gov is
available here:
https://www.weather.gov/documentation/services-web-api





Details:

The forecast for a location is available via a single call to
forecast.weather.gov using the latitude and longitude coordinates for
that
location, like so:
https://forecast.weather.gov/MapClick.php?lat=$LAT&lon=$LON&FcstType=
digit
al$FORMAT
    Where $LAT is the latitude, $LON is the longitude, and
    $FORMAT is either DWML or JSON

The API needs two calls to retrieve that same data if referenced to
latitude and longitude. The first is to cross reference the
latitude/longitude pair to a Weather Forecast Office (WFO) and
gridpoint
(X/Y coordinates):
https://api.weather.gov/points/$LAT,$LON
    Where $LAT is the latitude and $LON is the longitude
The second call uses the WFO and gridpoint to then retrieve the data:
https://api.weather.gov/gridpoints/$WFO/$gridX,$gridY/forecast/hourly
    Where $WFO is the 3 letter identifier of the WFO for that
    location and $gridX and $gridY are the grid coordinates
This process is detailed in the Examples tab of the API documentation
site
linked above.

The API application has many formats available, but by default will
typically return either geoJSON or json-LD. Please see either the
specification file at api.weather.gov/openapi.json or view the
Specification tab at www.weather.gov/documentation/services-web-api
for
more information. NOTE: geoJSON and json-LD differ from the JSON
output by
the Forecast application, so users will most likely need additional
work
to ingest.

In order to retrieve the data in DWML format, users will need to add
an
Accept header to the second API call, as shown in the Detailed
Example
below.

Detailed Example:

Here is the current link to retrieve the forecast in DWML format via
the
Forecast application for Kansas Citys Downtown:
https://forecast.weather.gov/MapClick.php?lat=39.2985&lon=-
94.4597&FcstType=digitalDWML
Here is the link for JSON output for the same location:
https://forecast.weather.gov/MapClick.php?lat=39.2985&lon=-
94.4597&FcstType=digitalJSON

In advance of termination of the above forecast digitalDWML and
digitalJSON, users should update their systems to use the following
calls
to the API for comparable data. The first call passes the
latitude/longitude pair to the API to discover the WFO and gridpoint.
Following the example of Kansas Citys Downtown, users would first
make
this call to the API:
https://api.weather.gov/points/39.2987,-94.4597
Among other information, this will return the following Properties:
  "gridId": "EAX",
  "gridX": 48,
  "gridY": 60,
These are then passed to the API to pull out the forecast data:
https://api.weather.gov/gridpoints/EAX/48,60/forecast/hourly
This will return the hourly forecast in GeoJSON format.

To retrieve the data in DWML format instead of the JSON forecast,
users
will add an Accept header with the value
  application/vnd.noaa.dwml+xml
to the request. Users will need to consult the documentation for
their
programs HTTP library on how to add a request header.

Discussions about the API and its use can be found here:
https://github.com/weather-gov/api/discussions

Known Errors with the API:

DIS and NCO are aware of an issue where data retrieval from the API
can
fail, requiring a retry. Users should add error handling and a retry
process into their scripts, adding a delay between retries to avoid
overloading the API service. The development and implementation
groups are
working to implement a code update to address this issue. Full
resolution
of these errors is expected by this fall.

For problems or operational issues with the Forecast or API
applications,
please contact:
 NCEP Central Operations
 Tech Control
 nco.ops@noaa.gov

For questions about the details of the termination in this notice,
please
contact:
 NCEP Central Operations
 Implementation and Data Services Branch, Onboarding Team
 idp-feedback@noaa.gov
or
 nws.webfeedback@noaa.gov

National Service Change Notices are online at:

https://www.weather.gov/notification/