Announcing V1 of the WDFN APIs

The new Water Data APIs provide programmatic pathways to accessing all USGS Water Data for the Nation (WDFN), providing a consistent interface for accessing all data from the National Water Information System.

In May 2025 we announced the first release of the modernized Water Data APIs . These new APIs are succeeding the WaterServices family of APIs, which will be decommissioned in early 2027 as part of NWISWeb Decommission Campaign 3 . The new Water Data APIs provide programmatic pathways to accessing all USGS data displayed on https://waterdata.usgs.gov , eliminating the need for complicated web scrapers and providing a consistent interface for accessing all data from the National Water Information System (NWIS).

Back in that original May announcement, we said:

We’re currently rolling out version 0 of these APIs, which are still under active development. In the future, if we need to make breaking changes to the APIs, we’ll deploy the new version of the APIs to a new URL. For example, the next version will be v1. We’ll then be able to run v0 and v1 in parallel for a period of time allowing you to migrate over before we shut down the old version.

Since then, we’ve notably expanded the number of endpoints and data types these APIs publish (including most recently our new peak flows service ), made queries more flexible across endpoints , and spent significant time improving query performance, documentation, and other user experience features to make these services as friendly and easy-to-use as possible. After two years of high-intensity development, these services are now delivering all the data types and supporting all the features we originally envisioned for the platform.

As such, we’re now announcing the “V1” release of the Water Data APIs. While this release is primarily marking the milestone of the modernized APIs being fully available, there will be several breaking changes from V0 of the application. The rest of this post will walk through what’s changing, what you’ll need to do, and what’s coming next after this release.

What does an API version mean?

One focus of Water Data for the Nation’s API modernization project was to improve the long-term maintainability of our APIs going forward. Specifically, we wanted to make sure we’d be able to continue developing our services as technology changes and user needs evolve, but that users could also feel comfortable developing against our services without worrying that behaviors they rely on would suddenly disappear.

Versioning is our way to accomplish those goals. As our documentation on Water Data API’s versioning says:

We aim to not release any breaking changes within a single version of an API. This means that any query which currently succeeds against the v0 of the APIs should continue to succeed against v0, though you might need to make some updates when we release v1. It doesn’t mean that we won’t make changes to the API’s interface or that the underlying data a query searches for won’t change.

Major versions are included as part of the API’s URL. For instance, V0 of the Water Data APIs was hosted at https://api.waterdata.usgs.gov/ogcapi/v0 , while V1 is now available from https://api.waterdata.usgs.gov/ogcapi/v1 . By saving breaking changes for these “major” version upgrades, we’re able to introduce new concepts in a way that allows users to migrate to the newest version of our services at their own pace.

What’s changing from V0?

The vast majority of users will see no changes between V0 and V1. However, there will be several breaking changes impacting users who download data in CSV format (?f=csv) and use the "qualifier" column, who use the "begin", "end", "begin_utc", "end_utc", "state_name" or "hydrologic_unit_code" columns in /time-series-metadata, or who use the "time" column of /field-measurements and /latest-field-measurements.

Changes to CSV responses

V0 of Water Data APIs returned the "qualifier" field in CSV responses as a JSON array. For instance, an observation with a qualifier of "ESTIMATED" would have its qualifier returned as ['ESTIMATED'], with single quotes around each qualifier value and the full list of qualifiers contained in square brackets.

V1 “unpacks” these arrays, removing the square brackets and quotes. That same "ESTIMATED" qualifier will now be returned as ESTIMATED. Multiple qualifiers will be separated by commas within a single column.

We’re making this change to make it easier to develop tools that use user-provided USGS water data. Right now, some tools that help download data in CSV format (like dataRetrieval ) do this “unpacking” to make qualifiers more useful for users, while other tools (like Water Data for the Nation’s Monitoring Location Pages) return the CSV exactly as the API provides it. By doing this “unpacking” by default, we can improve consistency in outputs from downstream tooling and help other software (like PeakFQ ) better anticipate the format in which users will provide their data.

Changes to /time-series-metadata

V0 of the /time-series-metadata endpoint initially included "begin" and "end" columns representing the earliest and most recent published observation of a time series. However, these datetimes were published in a site’s local time, without time zone information, making it difficult to know the precise instant they actually represented.

Updating these columns to include time zone information would change their data types, which we viewed as a breaking change requiring a major version release to implement. To address this, V0 has had two columns, "begin_utc" and "end_utc", providing the same information as "begin" and "end" but in the UTC time zone, with time zone information attached.

In V1, the "begin" and "end" columns now provide datetimes in UTC with time zone information. As such, the "begin_utc" and "end_utc" columns are fully redundant and have been removed. Users will need to update their applications as a result – either changing usage of "begin_utc" and "end_utc" to "begin" and "end", or ensuring that their application can ingest data in UTC with a time zone indicator (Z) at the end.

V0 of /time-series-metadata additionally provided "state_name" and "hydrologic_unit_code" as columns in the response. These fields are actually monitoring location metadata, and were already available from the /monitoring-locations endpoint, but were duplicated and added to this endpoint to make it easier to find all data collected within a given state or HUC .

Two improvements have made this duplication unnecessary. First, we released a combined metadata endpoint which lets users query data collections by all monitoring location metadata, not just two selected fields. This endpoint additionally allows filtering by the type of data being collected and includes manual field visit records. Second, we enhanced our core data endpoints to support querying by any monitoring location metadata , including these two fields.

As such, we no longer believe this duplication is useful, and it may cause confusion about why multiple time series at a single monitoring location would need to separately publish their state or HUC information. Users will need to update their requests to use the /combined-metadata endpoint or to skip querying /time-series-metadata altogether.

Changes to /field-measurements and /latest-field-measurements

V0 of the /field-measurements endpoint, and the /latest-field-measurements endpoint which mirrors it, published time as a datetime object. However, timestamps are not always known precisely to the second for some field measurements (just like some peak flows ); for example, older hand-written data sheets may not have preserved the time of day or exact date a measurement was taken.

While standards exist for supporting uncertain and approximate datetimes , these have not been broadly adopted and are not supported by the databases that underpin the modernized Water Data APIs. As such, in V1 these endpoints take the same approach as peak flows and break temporal information into multiple fields.

V0 of these endpoints already has fields for "year", "month", "day", and "time_of_day". These fields are set to null whenever a field measurement cannot be resolved down to that level. For example, a month of 2 and a day of null means that a field measurement was known to be taken at some point in February, but on an unknown day.

In V1, the "time" field will be updated to be a date (in UTC), rather than a datetime. If the month or day of a field measurement are unknown, those fields will be set to 01 in the "time" field, and null in the "month" or "day" field respectively. We use these placeholders to allow this data to be returned by temporal queries, while still indicating when a date is not known with perfect precision. Users will need to update their code to use the "time_of_day" column when observation time is needed, and to expect "time" to return a date.

What do I need to do?

If your applications are still using WaterServices, make sure to migrate before WaterServices is decommissioned in early 2027 . The modernized Water Data APIs are the primary source for USGS water data, and this V1 is a perfect opportunity to migrate your application.

If your application is not using /time-series-metadata, /field-measurements, /latest-field-measurements, or the CSV formatter, all you need to do is update https://api.waterdata.usgs.gov/ogcapi/v0/ in your code to https://api.waterdata.usgs.gov/ogcapi/v1/ . We’ll also start automatically redirecting these non-impacted requests from V0 to V1 in the coming weeks, migrating users to the new version with no action required on their side. If you notice a request to a V0 endpoint now includes links to V1 resources, that means your request has been automatically migrated to V1.

If you use dataRetrieval, forthcoming package versions will include updates to use the latest API versions. See the documentation for the R package and Python package for more information.

If your application is using any of the impacted endpoints (or CSV responses), you’ll need to update your application. Those updates include:

• Updating anything using CSV responses for the new qualifier format,
• Swap /times-series-metadata requests using monitoring location metadata to use the /combined-metadata endpoint instead, or to skip querying /time-series-metadata altogether,
• Either swap /time-series-metadata requests from using "begin_utc" and "end_utc" to "begin" and "end", or ensuring your application can ingest data in UTC with a time zone indicator (Z),
• Update applications querying /field-measurements to use the "time_of_day" column when observation time is needed, and to expect "time" to return a date.

The V0 /time-series-metadata, /field-measurements, and /latest-field-measurements endpoints will remain online until June 2027. Other endpoints will be automatically redirected in the coming weeks. Requests using the CSV format on endpoints with qualifier fields will not be automatically redirected until June 2027.

We will redirect all requests from V0 of these APIs to V1 in mid-2027. We will publish another notification before that redirect is implemented. At this point, code using V0 that was not updated may encounter breaking changes.

What’s next?

We’re thrilled to be reaching the end of this multi-year federal IT modernization project. The new WDFN APIs are already serving more than ten million requests per day from tens of thousands of daily active users, helping the USGS become one of the highest-traffic service providers using data.gov’s API services . But we’re not done yet.

We’ve released hundreds of non-breaking updates to V0 of these APIs in the past two years, and will continue to update and improve V1 in ways that don’t break existing workloads. We’re also working to continue expanding the standards we support, the types of data we publish, and the amount of metadata we provide about our methods and data collections. Subscribe to the Water Data for the Nation newsletter to receive updates about changes to water data APIs and our other modernization efforts, and email wdfn@usgs.gov with any questions or feedback about this work.