Migrating to modernized APIs

Page contents:

• Migrating from /dv to /daily
  • From WaterServices JSON
  • From WaterServices RDB
  • From WaterServices WaterML2
• Migrating from /site to /monitoring-locations
• Migrating from /site to /time-series-metadata
• How can I query for multiple monitoring locations, parameter codes, time series IDs, or other parameters at once?
• How can I download all the data for a HUC, basin, county, or other boundary area?

This guide provides resources from migrating from specific legacy APIs, hosted on waterservices.usgs.gov, to their modernized replacements on api.waterdata.usgs.gov. It will be continuously updated as additional modernized endpoints are released.

Specifically, this guide will help you move from APIs listed in the left column to their replacement listed on the right:

If you were using https://waterservices.usgs.gov/nwis/stats/ , more information about the modernized replacement will be available soon. If you were using https://waterdata.usgs.gov/nwis/qwdata , you should look at the documentation for the samples-data API.

The new APIs listed in the table are all hosted on https://api.waterdata.usgs.gov/ogcapi/ and implement the OGC API - Features standard. You can find an overview walking through how these APIs are structured at this link.

If you're going to make more than a few queries per hour, you'll need to provide an API key as part of your request. You can sign up for an API key here, and learn more about how to use API keys here.

This page walks through the new variable names used by the modernized APIs, listing where the variables returned by each WaterServices endpoint can now be accessed. When these variables have been intentionally discontinued, they are listed as "no longer provided". Variables which may be provided in the future are instead listed as "not currently available".

The bottom of this page additionally provides advice on how to translate common query patterns to the modernized services.

Migrating from /dv to /daily

From WaterServices JSON

The top-level metadata in the JSON object ("name", "declaredType", "scope", "nil", "globalScope", and "typeSubstituted") will no longer be returned.

The "queryInfo" block inside the top-level "value" key will no longer be returned. The "requestDT" has an equivalent in the "timeStamp" field of the /daily response object. The provisional data statement may be accessed at this link.

The remaining "timeSeries" block contains one section per time series included in the response, each of which contains a "sourceInfo" block, a "variable" block, a "values" block, and a "name" block. The "name" block combines the "agency_code" and "monitoring_location_number" fields in the /monitoring-locations endpoint with the "parameter_code" and "statistic_id" fields in the /daily endpoint. The other three blocks are represented in one of the below tables. Note that the /daily endpoint returns one feature per observation, rather than grouping per timeseries, which may require refactoring existing workflows.

The "sourceInfo" block is now provided by the /monitoring-locations endpoint. As such, the field names listed on the right side of the table below represent fields in the /monitoring-locations endpoint.

Certain portions of the "variable" block are now provided by the /time-series-metadata endpoint. These are specifically mentioned in the table below. The "id" field in the time-series-metadata endpoint corresponds to the "time_series_id" field in the /daily endpoint, and can be used to join data from the two endpoints together.

Fields in the "values" block are provided by the /daily endpoint.

From WaterServices RDB

Most of the header of the RDB file is no longer provided. The provisional data statement may be accessed at this link.

The monitoring location metadata at the top of the RDB file is now available from the /monitoring-locations endpoint:

#    USGS 01094400 NORTH NASHUA RIVER AT FITCHBURG, MA

This line contains three pieces of data:

• The first, "USGS", is called "agency_code" in the /monitoring-locations endpoint.
• The second, "01094400", is called "monitoring_location_number" in the /monitoring-locations endpoint. These two combined are called "monitoring_location_id" in the /daily endpoint, and "id" in the /monitoring-locations endpoint.
• The third, "NORTH NASHUA RIVER AT FITCHBURG, MA", is called "monitoring_location_name" in the /monitoring-locations endpoint.

Variable documentation lines are now available either through the collection schema page or the OpenAPI documentation.

The next lines contain time series metadata now primarily available from the /time_series_metadata endpoint:

# Data provided for site 01094400
#    TS_ID       Parameter    Statistic  IV_TS_ID       Description
#    64060       00060        00003      65937          Discharge, cubic feet per second (Mean)

This line contains five pieces of information:

• "TS_ID" is now called "time_series_id" in the /daily endpoint and "id" in the /time_series_metadata endpoint.
• "Parameter" is now called "parameter_code" in both the /daily and /time_series_metadata endpoints.
• "Statistic" is now called "statistic_id" in both the /daily and /time_series_metadata endpoints.
• "IV_TS_ID" is not currently available.
• "Description" is now called "parameter_description" in the /time_series_metadata endpoint.

The remainder of the file generally contains a number of lines following the same general table structure:

agency_cd	site_no	datetime	64060_00060_00003	64060_00060_00003_cd

The first three of these columns are returned as fields in either the /daily or /monitoring-locations endpoints:

• "agency_cd" is now called "agency_code" in the /monitoring-locations endpoint.
• "site_no" is now called "monitoring_location_number" in the /monitoring-locations endpoint. The "monitoring_location_id" field in /daily and the "id" field in /monitoring-locations is made by combining the agency code and monitoring location number.
• "datetime" is now called "time" in the /daily endpoint.

The remaining columns return metadata in their column names, which is now returned in distinct fields instead. Column names combined three pieces of metadata separated by underscores. Taking 64060_00060_00003 as an example:

• "64060" is now returned as a value in the "time_series_id" field of the /daily endpoint.
• "00060" is now returned as a value in the "parameter_code" field of the /daily endpoint.
• "00003" is now returned as a value in the "statistic_id" field of the /daily endpoint.

Values that were under columns named following this pattern are now called "value" in the /daily endpoint.

Values that were under columns ending in _cd have been split into two fields. Values of P and A, indicating whether the data is provisional or has been approved, are now returned in the "approval_status" field of the /daily endpoint. Other values are now returned in the "qualifier" field of the /daily endpoint.

From WaterServices WaterML2

The ns1:queryInfo block is no longer provided. The ns2:note title="requestDT" field is now called "timeStamp".

We additionally no longer provide the references to XML and WaterML schemas used by the WaterML2 response object. These are not included in the table below.

Migrating from /site to /monitoring-locations

Requests to /site which either did not include "seriesCatalogOutput" or set "seriesCatalogOutput=false" can be entirely replaced by the /monitoring-locations service.

Migrating from /site to /time-series-metadata

Requests to /site which set "seriesCatalogOutput=true" are only partially replaced by the /monitoring-locations endpoint. The fields which are now returned by the /monitoring-locations endpoint are listed below.

Period of record information for water quality data is now provided by the USGS samples data API /summary endpoint. Documentation for that endpoint is available here.

Period of record information for site visits are not yet available from modernized services.

Period of record information for time series data, including both instantaneous values and daily values, is available from the /time-series-metadata endpoint. You can find all time series for a given monitoring location by querying using the monitoring_location_id parameter.

How can I query for multiple monitoring locations, parameter codes, time series IDs, or other parameters at once?

The modernized APIs only support one value per query parameter in most GET requests. As such, more complex filters require one of two approaches:

• Split your query into several smaller queries. For instance, rather than trying to write a single query for multiple monitoring locations, query for each monitoring location separately. This will likely be faster than trying to write more complicated queries, particularly if the complex query returns multiple pages of data.
• Alternatively, send your queries as POST requests using CQL2 filter expressions.

How can I download all the data for a HUC, basin, county, or other boundary area?

The new data endpoints do not have set arguments that let you filter down to specific areas. Instead, make two distinct queries to the APIs:

• First, query the /monitoring-locations endpoint to get a list of monitoring locations which fall inside your desired query area.
• Then use that set of monitoring location IDs ("id" in the /monitoring-locations endpoint, "monitoring_location_id" in all other endpoints) to query your desired endpoint.

The /daily endpoint additionally supports using the bbox argument to restrict your query only to sites in a specified spatial region.