Public Information Statement
Issued by NWS National HQ
Issued by NWS National HQ
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/