As a user, I want to evaluate NWM data served by the newer WRDS NWM API.

[HankHerr-NOAA]

The service is hosted at the NWC, so the URL will not be shared. But code changes will be needed, hence this ticket. The new API is currently deployed in parallel with the legacy NWM API. The WRDS team hopes to decommissioning the NWM API in July, but we've been given instructions that (1) the legacy API cannot be decommissioned until the WRES is changed, and (2) changing the WRES to use the new API is behind HEFS and Water Supply work by the WRDS team. Since the same resources are employed to support both WRES and WRDS, that impacts the scheduling of this work.

Other tickets seemingly related to this one that may be addressed at the same time:

#146
#236
#433

Assigning this to 7.5, knowing that it may slip to 7.6 or later. Thanks,

Hank

[HankHerr-NOAA]

Bringing this ticket to the top of the list, again. NWM 3.1 becomes operational in mid-August. The WRDS team needs to spend time updating their NWM APIs. They would rather not update the legacy API which is currently employed by the WRES, but that would require the WRES to be updated quickly to work with the new API. I plan to discuss this today or tomorrow with Fernando and the WRDS team,

Hank

[james-d-brown]

I may be able to carve out some time for this, unsure. It depends how comprehensively different the old and new APIs might be. There is also a question of access and whether I can stage an example service with a small amount of data on localhost to simplify development. In principle, it can be implemented without that, but it leads to more back-and-forth at UAT time if working only from an api for the requests and responses.

[HankHerr-NOAA]

Thanks, James! I might also ask for some of Evan's time if that helps.

I'm going to share some JSON examples of old and new API responses serving comparable data, once I can get Gautam to send me the Swagger URL for the new, on-prem API (which he gave me before, but I can't find). I'll also share some partially redacted URLs to illustrate differences in how the requests need to be constructed.

To be honest, I think the WRDS team is still going to need to update the legacy API to serve 3.1 data. The cutover is planned for August 18. Normally, when switching to a new API, we would want some period of overlap to give our users time to migrate. If we allow for two weeks of overlap, that would leave us with an early August deployment of 7.6 that would include the use of the new API. That is a very short time line. I don't know that that is realistic to do the development and testing needed to shake out all of the issues.

Hopefully, I'll have example JSONs and URLs later this morning,

Hank

[james-d-brown]

That is definitively an unrealistic timeframe, based on past experience with WRDS. End of August is more realistic.

[HankHerr-NOAA]

I have the URL for the Swagger documentation. Omitting the NWC-specific hostname (see VLab if you want to know that), here is the URL:

https://omitted/nwm/v1/docs/

Hank

[HankHerr-NOAA]

Here is the URL using the legacy API:

https://omitted/api/nwm3.0/v3.0/streamflow/medium_range/streamflow/nwm_feature_id/5907079/?forecast_type=deterministic&proj=HANK&reference_time=%2820260701T00Z%2C20260709T00Z%5D

The response (with content omitted):

example_json_response_old_api_1.json.gz

Here is an equivalent URL using the new API:

https://omitted/nwm/v1/streamflow/forecast/nwm_feature_id/5907079/?configuration=medium_range&before_reference_datetime=2026-07-09T00%3A00%3A00Z&after_reference_datetime=2026-07-01T00%3A00%3A00Z

The response (no omissions needed):

example_json_response_new_api_1.json.gz

One difference: the new API does not include data for 7/9 0Z; the old one does. Note that the words "before" and "after" in the parameter names imply the endpoints are exclusive. However, I don't think that is actually the case; I believe that the bounds are inclusive. I've emailed Gautam letting him know about this difference and asking for a clarification.

I'm going to step through the data slowly to see if there are any numerical differences,

Hank

[HankHerr-NOAA]

I just noticed that the new API URL results in the full ensemble. Let me see if there is a deterministic option so that it is truly equivalent to the old API request in the previous comment,

Hank

[HankHerr-NOAA]

There does not appear to be a parameter that allows for only getting the first member of the MRF. So, for a truly comparable example, here is the output if OLD API request is modified so that forecast_type=ensemble:

example_json_response_old_api_1_full_ensemble.json.gz

Thanks,

Hank

(EDIT: Original file uploaded was removed. New file attachment created.)

[HankHerr-NOAA]

I don't believe this is true:

However, I don't think that is actually the case; I believe that the bounds are inclusive. I've emailed Gautam letting him know about this difference and asking for a clarification.

The lower bound appears to be exclusive for the both the old and new API. Using a lower bound on the reference times of 7/1 0Z (in the new API, this is the after... parameter) results in the first forecast being for 7/1 6Z.

The new API appears to use an exclusive upper bound (i.e., before... parameter), while the old API does not. Again, I'll ask Gautam for clarity, but I'm guessing both endpoints are now exclusive in the new API.

Thanks,

Hank

[HankHerr-NOAA]

Basic spot checks of the data look good. I'm going to check a few more configurations,

Hank

[HankHerr-NOAA]

Short range requests...

Legacy URL:

https://omitted/api/nwm3.0/v3.0/streamflow/short_range/streamflow/nwm_feature_id/5907079/?proj=HANK&reference_time=%2820260701T00Z%2C20260709T00Z%5D

Legacy response:

example_json_response_old_api_2.json.gz

New URL:

https://omitted/nwm/v1/streamflow/forecast/nwm_feature_id/5907079/?configuration=short_range&before_reference_datetime=2026-07-09T00%3A00%3A00Z&after_reference_datetime=2026-07-01T00%3A00%3A00Z

New response:

example_json_response_new_api_2.json.gz

Hank

[HankHerr-NOAA]

AnA requests...

Legacy URL:

https://omitted/api/nwm3.0/v3.0/streamflow/analysis_assim/streamflow/nwm_feature_id/5907079/?proj=HANK&reference_time=%2820260701T00Z%2C20260709T00Z%5D

Legacy response:

example_json_response_old_api_3.json.gz

New URL:

https://omitted/nwm/v1/streamflow/forecast/nwm_feature_id/5907079/?configuration=analysis_assim&before_reference_datetime=2026-07-09T00%3A00%3A00Z&after_reference_datetime=2026-07-01T00%3A00%3A00Z

New response:

example_json_response_new_api_3.json.gz

Hank