What's new with WDFN APIs - Summer 2026 Edition

A new endpoint for peak flows is now available, queries now have additional metadata fields for filtering, and a new UI theme has been released for HTML responses.

It’s been a busy few months for Water Data for the Nation’s Water Data APIs , the services that publish USGS water data in machine-readable formats. This post walks through a few recent updates to these APIs.

Peak flow service now available

We’ve released a new endpoint for peak flow values . This endpoint provides the same data as the legacy peaks service (hosted at https://nwis.waterdata.usgs.gov/usa/nwis/peak ), which will be retired this winter as part of NWISWeb Decommission Campaign 3 .

A data dictionary is available online , with definitions for all the variables returned by this endpoint. The dataRetrieval R package has a new read_waterdata_peaks() function for getting data from this endpoint, and the dataretrieval Python package has a corresponding get_peaks() function.

Sometimes the magnitude of a peak flow might be known, but not the precise time, day, or even month during which the flow occurred. At the same time, the database used by WDFN’s APIs doesn’t allow temporal queries against unknown or partial dates. For example, for some records, records may only show that the peak flow occurred in 1980, but not specifically when in 1980.

In order to enable temporal queries against the peaks endpoint, this endpoint has individual fields for the year, month, day, and time of day that a peak flow occurred. Each of these fields will be null if that specific date part is unknown. The time field returned by this endpoint (used by temporal queries), meanwhile, will set any unknown components of the date to "01", allowing these results to show up in temporal queries. So, in the 1980 example, the time field would show as “1980-01-01” so that the record is able to be queried; however, the month, day, and time_of_day fields will return null values.

Expanded querying

The /continuous and /daily endpoints now support many more query arguments, allowing queries to use any field returned by the monitoring location endpoint. This means that you can now query these endpoints using state name, hydrologic unit code, and more.

We’ll be expanding this functionality to the /field-measurements, /latest-continuous, /latest-daily, and /latest-field-measurements endpoints in the near future.

Browser UI updates

Last but not least, we’ve overhauled the HTML UI for the APIs, as displayed when loading API links in a web browser. The new UI uses the United States Web Design System throughout, giving it a cohesive appearance that aligns with the rest of WDFN, and attempts to make it easier to find exactly what you’re looking for. In particular, the new API landing page provides a more organized overview of what each endpoint is used for, and the new navigation bar should make it easier to find documentation and useful links when on the API website.

We’re continuing to work on and improve these services, and are focused on helping users migrate to the new APIs before WaterServices is decommissioned in Winter 2027. Please reach out to us at wdfn@usgs.gov with any questions or feedback you may have.