What's new with WDFN APIs?

What to expect from modernized replacements to the WaterServices family of APIs.

Introduction

For over 15 years, the USGS has provided machine-readable and automated access to water data via the WaterServices family of application programming interfaces (APIs), hosted at https://waterservices.usgs.gov/ . These APIs underpin all other USGS web delivery products – including products such as the National Water Dashboard and Water Data for the Nation – and have been incredibly effective at delivering water data to the public. Between October 2024 and March 2025 alone, these legacy APIs have handled more than 1.6 billion requests from almost 3.5 million distinct IP addresses.

Unfortunately, maintaining these legacy APIs has become more challenging over the years. WaterServices depends upon both hardware and software components which are reaching their end of life, and it has become increasingly difficult to add features or otherwise maintain as time goes on.

As such, we are releasing new, modernized API endpoints throughout rest of 2025 which will provide the same data that you’re used to but with a new API interface and response format. This blog post will walk through what you can expect from these new endpoints, when you’ll need to migrate over, and some of the most-requested new features these modernized services will provide.

This post focuses on four of the six services that currently comprise WaterServices:

• The “instantaneous values” or “iv” service, which provides automated measurements of current streamflow, gage height, and hundreds of other real-time data.
• The “daily values” or “dv” service, which provides mean, median, maximum, minimum, and/or other derived values of automated measurements.
• The “site” services, which provides information about USGS monitoring locations.
• And the “groundwater levels” service, which provides historical manually-recorded groundwater levels from monitoring locations served by the USGS.

If you’re using the samples data API , which replaced the qwdata service in 2024 , then you’re already using a modernized API and won’t need to make any changes. The WaterServices statistics service is being redesigned separately to better support Water Data for the Nation, and we will provide more information about its replacement in the future.

What to expect from the modernized APIs

So, what can you expect from the new APIs?

Our new modernized endpoints implement a standard known as “OGC API - Features ”. This API interface standard is promoted by the Open Geospatial Consortium and is in widespread usage by data providers. As a result, the modernized APIs should provide a similar interface to other data sources you may be using already, and one which will hopefully be an easy transition for your existing workflows.

New query strings

To talk about what that looks like in practice, let’s look at an example query to the legacy WaterServices APIs. The following URL is a query to the “dv” service, looking to retrieve daily values:

https://waterservices.usgs.gov/nwis/dv/?format=json&sites=02238500&period=P1D&parmCD=00065

This query requests data for a single monitoring location, which it specifies using a monitoring location number. It only wants the last day of data, which it specifies using the period argument. And it’s only looking for a single parameter code.

That same exact query against our new APIs, which are hosted on https://api.waterdata.usgs.gov/ , looks like this instead:

https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=json&monitoring_location_id=USGS-02238500&time=P1D&parameter_code=00065

The new APIs use more explicit naming conventions, moving away from abbreviations towards full names making our data more accessible. As a result, the new URL is a bit longer but is easier to understand.

Instead of using “dv”, this new query uses the “daily” service. Our “format” argument does get shortened to “f”, but the rest of the arguments are a bit more verbose. The “sites” argument becomes “monitoring location ID”, which includes the agency code for the monitoring location we want data from; the “period” argument becomes “time” but otherwise stays the same, and “parmCD” becomes “parameter code”. The key takeaway here is that the concepts of the query string are staying more or less the same, even though the format is changing a bit.

New response objects

A bigger change with the modernized APIs is what gets included in each response. That request to the legacy dv service will return a rather large and complex JSON object:

{ 
  "name": "ns1:timeSeriesResponseType", 
  "declaredType": "org.cuahsi.waterml.TimeSeriesResponseType", 
  "scope": "javax.xml.bind.JAXBElement$GlobalScope", 
  "value": { 
    "queryInfo": { 
      "queryURL": "http://waterservices.usgs.gov/nwis/dv/format=json&sites=02238500&period=P1D&parmCD=00065", 
      "criteria": { 
        "locationParam": "[ALL:02238500]", 
        "variableParam": "[00065]", 
        "parameter": [] 
      }, 
      "note": [ 
        { 
          "value": "[ALL:02238500]", 
          "title": "filter:sites" 
        }, 
        { 
          "value": "[mode=PERIOD, period=P1D, modifiedSince=null]", 
          "title": "filter:timeRange" 
        }, 
        { 
          "value": "methodIds=[ALL]", 
          "title": "filter:methodId" 
        }, 
        { 
          "value": "2025-04-16T13:20:02.573Z", 
          "title": "requestDT" 
        }, 
        { 
          "value": "811ff4c0-1ac5-11f0-a70d-2cea7f5e5ede", 
          "title": "requestId" 
        }, 
        { 
          "value": "Provisional data are subject to revision. Go to http://waterdata.usgs.gov/nwis/help/?provisional for more information.", 
          "title": "disclaimer" 
        }, 
        { 
          "value": "sdas01", 
          "title": "server" 
        } 
      ] 
    }, 
    "timeSeries": [ 
      { 
        "sourceInfo": { 
          "siteName": "OCKLAWAHA RIVER AT MOSS BLUFF, FL", 
          "siteCode": [ 
            { 
              "value": "02238500", 
              "network": "NWIS", 
              "agencyCode": "USGS" 
            } 
          ], 
          "timeZoneInfo": { 
            "defaultTimeZone": { 
              "zoneOffset": "-05:00", 
              "zoneAbbreviation": "EST" 
            }, 
            "daylightSavingsTimeZone": { 
              "zoneOffset": "-04:00", 
              "zoneAbbreviation": "EDT" 
            }, 
            "siteUsesDaylightSavingsTime": true 
          }, 
          "geoLocation": { 
            "geogLocation": { 
              "srs": "EPSG:4326", 
              "latitude": 29.0811111, 
              "longitude": -81.8808333 
            }, 
            "localSiteXY": [] 
          }, 
          "note": [], 
          "siteType": [], 
          "siteProperty": [ 
            { 
              "value": "ST", 
              "name": "siteTypeCd" 
            }, 
            { 
              "value": "03080102", 
              "name": "hucCd" 
            }, 
            { 
              "value": "12", 
              "name": "stateCd" 
            }, 
            { 
              "value": "12083", 
              "name": "countyCd" 
            } 
          ] 
        }, 
        "variable": { 
          "variableCode": [ 
            { 
              "value": "00065", 
              "network": "NWIS", 
              "vocabulary": "NWIS:UnitValues", 
              "variableID": 45807202, 
              "default": true 
            } 
          ], 
          "variableName": "Gage height, ft", 
          "variableDescription": "Gage height, feet", 
          "valueType": "Derived Value", 
          "unit": { 
            "unitCode": "ft" 
          }, 
          "options": { 
            "option": [ 
              { 
                "value": "Mean", 
                "name": "Statistic", 
                "optionCode": "00003" 
              } 
            ] 
          }, 
          "note": [], 
          "noDataValue": -999999, 
          "variableProperty": [], 
          "oid": "45807202" 
        }, 
        "values": [ 
          { 
            "value": [ 
              { 
                "value": "35.12", 
                "qualifiers": [ 
                  "P" 
                ], 
                "dateTime": "2025-04-15T00:00:00.000" 
              } 
            ], 
            "qualifier": [ 
              { 
                "qualifierCode": "P", 
                "qualifierDescription": "Provisional data subject to revision.", 
                "qualifierID": 0, 
                "network": "NWIS", 
                "vocabulary": "uv_rmk_cd" 
              } 
            ], 
            "qualityControlLevel": [], 
            "method": [ 
              { 
                "methodDescription": "", 
                "methodID": 170268 
              } 
            ], 
            "source": [], 
            "offset": [], 
            "sample": [], 
            "censorCode": [] 
          } 
        ], 
        "name": "USGS:02238500:00065:00003" 
      } 
    ] 
  }, 
  "nil": false, 
  "globalScope": true, 
  "typeSubstituted": false 
} 

There is a lot of information that comes along with a single USGS measurement, all wrapped up in a very deeply nested JSON object that can be a bit tricky to pull things out of.

The new APIs cut a lot of this out and return a much flatter GeoJSON object:

{ 
    "type":"FeatureCollection", 
    "features":[ 
        { 
            "type":"Feature", 
            "properties":{ 
                "timeseries_id":"a728d6c12d6a4fb89045a7794a1a8bee", 
                "statistic_id":"00003", 
                "monitoring_location_id":"USGS-02238500", 
                "value":"35.12", 
                "approval_status":"Provisional", 
                "last_modified":"2025-04-16T07:20:47.740498+00:00", 
                "parameter_code":"00065", 
                "time":"2025-04-15", 
                "unit_of_measure":"ft", 
                "qualifier":null 
            }, 
            "id":"74805eff-59eb-458c-9138-dd0141b626bb", 
            "geometry":{ 
                "type":"Point", 
                "coordinates":[ 
                    -81.8808333333333, 
                    29.0811111111111 
                ] 
            } 
        } 
    ], 
    "numberReturned":1, 
    "links":[ 
        { 
            "type":"application/geo+json", 
            "rel":"self", 
            "title":"This document as GeoJSON", 
            "href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=json&monitoring_location_id=USGS-02238500&time=P1D&parameter_code=00065" 
        }, 
        { 
            "rel":"alternate", 
            "type":"application/ld+json", 
            "title":"This document as RDF (JSON-LD)", 
            "href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=jsonld&monitoring_location_id=USGS-02238500&time=P1D&parameter_code=00065" 
        }, 
        { 
            "type":"text/html", 
            "rel":"alternate", 
            "title":"This document as HTML", 
            "href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?f=html&monitoring_location_id=USGS-02238500&time=P1D&parameter_code=00065" 
        }, 
        { 
            "type":"application/json", 
            "title":"Daily values", 
            "rel":"collection", 
            "href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily" 
        } 
    ], 
    "timeStamp":"2025-04-16T13:39:00.464164Z" 
} 

That GeoJSON object can be imported directly into your programming language of choice, or a GIS, without requiring any transformation. Early feedback has suggested that this response is much easier to turn into data frames or tables than the legacy JSON responses were.

Of course, this GeoJSON response can only be so much smaller by cutting out a lot of the fields that were present in the legacy response. The biggest change is that monitoring location metadata, such as hydrologic unit codes (HUCs) or basin codes, will no longer be returned as part of every request to the “data” services, meaning the daily values, instantaneous values, and groundwater level services.

We’re making this change because the vast majority of our traffic comes from people who always want the newest measurements at a specific list of monitoring locations, meaning that a large chunk of each response object is taken up by data that those users already have and don’t need to download again. Cutting this response object down to just the information about each daily values measurement is going to help us be more efficient and decrease the amount of time it takes you to get the data you need.

You can still get all of the metadata about a monitoring location by using the new /monitoring-locations endpoint . In general, these APIs are moving towards being more modular, where each piece of information lives in one and only one place, but should be easy to find and access. For that reason, each of our endpoints have specific keys that you can use to look up corresponding data in other endpoints – for instance, the “monitoring location id” field in the daily values response corresponds to the “id” field in the monitoring locations endpoint, so you can easily query that endpoint to get all the monitoring location metadata corresponding to your daily values.

Browser-based exploration

If you navigate to the root URL of these APIs (https://api.waterdata.usgs.gov/ogcapi/v0/ ), you should see a list of all of the OGC-compliant modernized endpoints that are currently available. This new homepage makes it easier to explore the data that’s available from the new services. Clicking the buttons on the cards on this page will make a small query to the relevant service, returning a map with its first ten results. For instance, this link will show you the first ten daily values records provided by the service:

https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items

You’ll also notice a link in the top right of the webpage to the JSON version of this response. If the APIs think your requests are coming from a web browser, they’ll default to giving you the HTML version of this page; otherwise, they’ll give you the JSON version. You can append ?f=json to the URL to always get the JSON version, or ?f=html to get the HTML – or even ?f=csv to get the output as a CSV.

API Keys

A big change with the modernized endpoints is that they will require you to provide an API key to make more than a handful of requests per hour. API keys can be obtained (for free!) from https://api.waterdata.usgs.gov/signup .

If you don’t provide an API key, you’ll be limited to 50 requests per IP address per hour. If you register for a key and pass it via the api_key argument or the X-Api-Key header, you’ll get access to 1000 requests per hour. More documentation about using API keys with these services can be found at this link .

Pagination

One other change about the modernized APIs is that there is now a maximum number of observations the service will return in a single request. If your request exceeds that limit of records, then the response will be broken up into multiple pages each containing part of the response. By default, this limit is set very low – currently to 10 results – but can be increased by setting the limit= argument to a higher number, up to a maximum of 10,000.

To find the next page of data, look for a link in the “links” section of the geojson response with a “rel” value of “next”:

{
    "links":[
        {
            "type":"application/geo+json",
            "rel":"next",
            "title":"Items (next)",
            "href":"https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?offset=1&limit=1"
        }
    ]
}

Don’t try and generate these links for yourself, as the structure of “next” links may change over time.

This link will lead to the next page of data. Note that it won’t include your API key, which you’ll need to add yourself, because we don’t want you to accidentally save that in data that you might send to other people.

API versioning

These new APIs also introduce a new method to version our APIs, making it easier for us to gradually release new features and continue to modernize these services in the future. You might have noticed that the URLs in this blog post have a “v0” in their URL. That represents the current version of these APIs.

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.

Importantly, our definition of “breaking changes” only includes changes to the API interface itself. Within a single API version, our goal is that requests which have been possible will continue to be possible, and as such things like field names and the response formats available will stay stable. However, we can add additional fields to an endpoint, change the default values of arguments (such as limit), add new query parameters, or change the order of fields in response objects without needing to increment the version.

Documentation

We’ve been working on building out documentation for these new endpoints to make it easier to learn and adopt these services into your workflows. Right now, we provide two main categories of documentation: short reference “Swagger” documentation , and longer tutorials with more examples . We’ll continue to develop both of these resources as time goes on.

Timing and future plans

Those are the biggest changes coming with the next generation of USGS water data APIs. It’s worth discussing our future plans for these services, as well as talking about when you should look to migrate your existing applications over to the new services.

Right now, navigating to https://api.waterdata.usgs.gov/ogcapi/v0/ will show you three available services. That includes modernized replacements for the daily values and sites services, plus a brand new “timeseries metadata” service that provides additional information for each data collection activity happening at a given monitoring location.

If you have workloads which use these services, you should consider migrating your applications over starting today. We do not currently have a date when WaterServices will no longer be available, but we expect the legacy service performance to degrade beginning in September 2025 due to changes in available hosting environments.

We expect to release a new “field measurements” endpoint in the near future, which will replace the groundwater levels service and additionally provide manual measurements of gage height and discharge, followed by an instantaneous values service which will be the last WaterServices endpoint to have a modernized replacement. We’ll advertise both of these new endpoints broadly when they’re made available and ready for you to migrate your workloads over to.

We understand that the migration from WaterServices is going to be a big change, and that it’s happening quickly. We want to be a resource for you during this transition! If you have questions or feedback, please get in contact through this form and we’ll do everything we can to assist you.

A new home for USGS water data APIs

The new APIs live on https://api.waterdata.usgs.gov , the new central hub for all modernized USGS water data APIs. There you will see links to a number of different endpoints, including for other USGS data like the National Imagery Management Service. You’ll also find a “documentation” tab which provides a central place for long-form API documentation. Finally, you’ll find a signup form for API keys. We’ll be updating this website to add more documentation and guides for using the new APIs.

Please subscribe to the Water Data for the Nation newsletter to receive updates about changes to water data APIs and other modernization efforts.