272
NOUS41 KWBC 031630 AAA
PNSWSH
Service Change Notice 24-50 Updated
National Weather Service Headquarters Silver Spring MD
1230 PM EDT Mon Jun 3 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: Updated: Migration of JSON and DWML Data Services to NWSs
API
 Application at api.weather.gov and Removal From
 forecast.weather.gov, Effective TBD

Updated to delay the change until a date to be determined, to add
context
for the decision by documenting deficiencies, and guidance for future
efforts.

Update:
The NWS is postponing the removal of the digitalDWML and digitalJSON
products from the Forecast application forecast.weather.gov until the
API
application can be upgraded to include the requisite data in the same
formats. Users are encouraged to continue migration to the API for
their
data pulls where possible, utilizing the updated documentation at
https://www.weather.gov/documentation/services-web-api to inform
their
transition.

Please note that the digitalDWML and digitalJSON services currently
reside
on a legacy system that will reach end-of-life at the end of June.
The
effort to stand these services up on the new infrastructure is
underway
and is expected to happen on or about the time the legacy system
reaches
end-of-life. The long-term plan is to enable the API to fully support
existing Forecast customers needs.


Effective at a date to be determined, 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 majority of 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.

Unavailable Data on the API in DWML format:

Data that is currently unavailable on the API in DWML but available
on
forecast.weather.gov is cloud cover, QPF (Quantitative Precipitation
Forecast), and wind gusts. Other datasets are incorrectly
categorized,
such as hourly when they are actually 12hr output - see the updated
documentation at
https://www.weather.gov/documentation/services-web-api
for a more detailed description.




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/