# Migrating to Modernized USGS Water APIs
Canonical URL: https://api.waterdata.usgs.gov/docs/ogcapi/migration/
> Map your waterservices.usgs.gov queries onto the equivalent api.waterdata.usgs.gov OGC API endpoints and response fields.


# Migrating to modernized APIs

**Page contents**:

- [Migrating from /iv to /continuous](#migrating-from-%2Fiv-to-%2Fcontinuous)
  - [From WaterServices JSON](#from-waterservices-json)
  - [From WaterServices RDB](#from-waterservices-rdb)
  - [From WaterServices WaterML2](#from-waterservices-waterml2)
- [Migrating from /dv to /daily](#migrating-from-%2Fdv-to-%2Fdaily)
  - [From WaterServices JSON](#from-waterservices-json-1)
  - [From WaterServices RDB](#from-waterservices-rdb-1)
  - [From WaterServices WaterML2](#from-waterservices-waterml2-1)
- [Migrating from /site to /monitoring-locations](#migrating-from-%2Fsite-to-%2Fmonitoring-locations)
- [Migrating from /site to /time-series-metadata](#migrating-from-%2Fsite-to-%2Ftime-series-metadata)
- [Migrating from /gwlevels to /field-measurements](#migrating-from-%2Fgwlevels-to-%2Ffield-measurements)
- [Migrating from /measurements to /field-measurements](#migrating-from-%2Fmeasurements-to-%2Ffield-measurements)
- [Migrating from /peak to /peaks](#migrating-from-%2Fpeak-to-%2Fpeaks)
- [How can I query for multiple monitoring locations, parameter codes, time series IDs, or other parameters at once?](#how-can-i-query-for-multiple-monitoring-locations%2C-parameter-codes%2C-time-series-ids%2C-or-other-parameters-at-once%3F)
- [How can I download all the data for a HUC, basin, county, or other boundary area?](#how-can-i-download-all-the-data-for-a-huc%2C-basin%2C-county%2C-or-other-boundary-area%3F)


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:

<div class="usa-table-container--scrollable" tabindex="0">

| If you were using...                                                    | Then you should use...                                        |
| ----------------------------------------------------------------------- | ------------------------------------------------------------- |
| Latest automated measurements from https​://waterservices.usgs.gov/nwis/iv/?     | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/latest-continuous>  |
| Historical automated measurements from https​://waterservices.usgs.gov/nwis/iv/? | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/continuous>         |
| https​://waterservices.usgs.gov/nwis/dv/?                              | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily>              |
| Discharge and gage height readings from https​://waterdata.usgs.gov/measurements/ | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/field-measurements> |
| Channel measurements from https​://waterdata.usgs.gov/measurements/ | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/channel-measurements> |
| https​://waterservices.usgs.gov/nwis/gwlevels/                        | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/field-measurements> |
| Monitoring location metadata from https​://waterservices.usgs.gov/nwis/site/? | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/monitoring-locations> |
| Period of record information from https​://waterservices.usgs.gov/nwis/site/? | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/time-series-metadata> |
| https​://waterdata.usgs.gov/nwis/peak | <https://api.waterdata.usgs.gov/ogcapi/v1/collections/peaks> |

</div>

If you were using https://waterservices.usgs.gov/nwis/stats/ , you should look at [the documentation for the statistics API](https://api.waterdata.usgs.gov/statistics/v0/docs). If you were using https://waterdata.usgs.gov/nwis/qwdata , you should look at [the documentation for the samples-data API](https://api.waterdata.usgs.gov/samples-data/docs).

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](/docs/ogcapi/). 

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](/signup), and [learn more about how to use API keys here](/docs/ogcapi/keys).

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 /iv to /continuous

Continuous data are collected via automated sensors installed at a monitoring location. They are collected at a high frequency and often at a fixed 15-minute interval. Depending on the specific monitoring location, the data may be transmitted automatically via telemetry and be available on WDFN within minutes of collection, while other times the delivery of data may be delayed if the monitoring location does not have the capacity to automatically transmit data.

These data were previously available from the `/iv` endpoint on WaterServices, and are now returned by the `/continuous` endpoint on the USGS Water Data APIs. To get just the most recent continuous value for each time series in the USGS network, use the `/latest-continuous` endpoint. 

Note that the `/continuous` endpoint only allows querying for three years of data at a time. For the best performance, break large queries up into multiple queries, one per year of data you're looking for.

### 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 `/continuous` response object. [The provisional data statement may be accessed at this link](https://waterdata.usgs.gov/provisional-data-statement/).

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 `/continuous` endpoint. The other three blocks are represented in one of the below tables. Note that the `/continuous` 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.

<div class="usa-table-container" tabindex="0">

| Field in the `/iv` "sourceInfo" block | Corresponding field in the `/monitoring-locations` response |
| ------------------------------------- | -------------------------------------------- |
| siteName                              | monitoring_location_name                                             |
| siteCode -> value                | monitoring_location_number . Included in the monitoring_location_id field in `/continuous`. |
| siteCode -> agencyCode                | agency_code ("network" is no longer provided). Included in the monitoring_location_id field in `/continuous`. |
| timeZoneInfo -> defaultTimeZone -> zoneOffset | No longer provided. |
| timeZoneInfo -> defaultTimeZone -> zoneAbbreviation | time_zone_abbreviation |
| timeZoneInfo -> daylightSavingsTimeZone -> zoneOffset | No longer provided. |
| timeZoneInfo -> daylightSavingsTimeZone -> zoneAbbreviation | No longer provided. |
| timeZoneInfo -> siteUsesDaylightSavingsTime | uses_daylight_savings |
| geoLocation -> geogLocation -> srs | All coordinates are in EPSG:4326, or use the CRS specified by the `crs` argument. |
| geoLocation -> geogLocation -> latitude | Provided as part of the "geometry" object. |
| geoLocation -> geogLocation -> longitude | Provided as part of the "geometry" object. |
| geoLocation -> localSiteXY | No longer provided. |
| note | No longer provided. |
| siteType | site_type |
| siteProperty -> "siteTypeCd" | site_type_code |
| siteProperty -> "hucCd" | hydrologic_unit_code |
| siteProperty -> "stateCd" | state_code |
| siteProperty -> "countyCd" | county_code |

</div>

Certain portions of the "variable" block are now provided by the `/time-series-metadata` and `/statistic-codes` endpoints. 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 `/continuous` endpoint, and can be used to join data from the two endpoints together.

<div class="usa-table-container" tabindex="0">

| Field in the `/iv` "variable" block | Corresponding field in the `/continuous` response |
| ------------------------------------- | -------------------------------------------- |
| variableCode -> value | parameter_code |
| variableCode -> network | No longer provided. |
| variableCode -> vocabulary | No longer provided. | 
| variableCode -> variableID | No longer provided. | 
| variableCode -> default | No longer provided. | 
| variableName | parameter in `/time-series-metadata` | 
| variableDescription | parameter_description in `/time-series-metadata` |
| valueType | No longer provided. |
| unit -> unitCode | unit_of_measure | 
| options -> option -> value | id in `/statistic-codes`. |
| options -> option -> name | No longer provided. | 
| options -> option -> optionCode | statistic_id | 
| note | No longer provided. |
| noDataValue | No longer provided. Missing data is now represented with null values. | 
| variableProperty | No longer provided. |
| oid | No longer provided. | 

</div>

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

<div class="usa-table-container" tabindex="0">

| Field in the `/iv` "values" block | Corresponding field in the `/continuous` response |
| ------------------------------------- | -------------------------------------------- |
| value -> value | value |
| value -> qualifiers | approval_status |
| value -> dateTime | time (now an ISO8601 YYYY-MM-DD date string) |
| qualifier -> qualifierCode | Approval status ("Approved" and "Provisional") are now called approval_status. Other qualifiers are called qualifier. |
| qualifier -> qualifierDescription | Not currently available. |
| qualifier -> qualifierID | Not currently available. | 
| qualifier -> network | No longer provided. |
| qualifier -> vocabulary | No longer provided. | 
| qualityControlLevel | No longer provided. |
| method -> methodDescription | Not currently available. | 
| method -> methodID | Not currently available. | 
| source | No longer provided. | 
| offset | No longer provided. | 
| sample | No longer provided. | 
| censorCode | No longer provided. | 

</div>

### 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](https://waterdata.usgs.gov/provisional-data-statement/).

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 `/continuous` 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](https://api.waterdata.usgs.gov/ogcapi/v1/collections/continuous/schema) or the [OpenAPI documentation](https://api.waterdata.usgs.gov/ogcapi/v1/openapi?f=html#/continuous/getContinuousFeatures).

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

```
# Data provided for site 01435000
#    TS_ID       Parameter Description
#    107389      00060     Discharge, cubic feet per second

```

This line contains three pieces of information:

- "TS_ID" is now called "time_series_id" in the `/continuous` endpoint and "id" in the `/time_series_metadata` endpoint.
- "Parameter" is now called "parameter_code" in both the `/continuous` and `/time_series_metadata` endpoints.
- "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	tz_cd	107389_00060	107389_00060_cd
```

The first three of these columns are returned as fields in either the `/continuous` 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 `/continuous` 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 `/continuous` endpoint.
- "tz_cd" is no longer provided. Time stamps now are in UTC and include time zone information.

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

- "107389", the monitoring location number, is now returned as a value in the "monitoring_location_id" field of the `/continuous` endpoint.
- "00060", the parameter code, is now returned as a value in the "parameter_code" field of the `/continuous` endpoint.

Values that were under columns named following this pattern are now called "value" in the `/continuous` 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 `/continuous` endpoint. Other values are now returned in the "qualifier" field of the `/continuous` 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.

<div class="usa-table-container" tabindex="0">

| Key in the `/iv` WaterML2 response | New endpoint | Corresponding field name |
| ---------------------------------- | ------------ | ------------------------ |
| ns1:timeSeries name | `/monitoring-locations`, `/continuous`, `/time-series-metadata` | This name object combines the agency_code and monitoring_location_number from the `/monitoring-locations` endpoint with the parameter_code and statistic_id returned by both the `/continuous` and `/time-series-metadata` endpoints. The agency code and monitoring location number are also combined to form the monitoring_location_id in `/continuous` and `/time-series-metadata` and the id field in `/monitoring-locations`.|
| ns1:siteName | `/monitoring-locations` | monitoring_location_name |
| ns1:siteCode | `/monitoring-locations` | monitoring_location_number |
| ns1:siteCode network | | No longer provided. | 
| ns1:siteCode agencyCode | `/monitoring-locations` | agency_code. The agency code and monitoring location number are combined to form the monitoring_location_id in `/continuous` and `/time-series-metadata` and the id field in `/monitoring-locations`. |
| ns1:timeZoneInfo siteUsesDaylightSavingsTime | `monitoring-locations` | uses_daylight_savings |
| ns1:defaultTimeZone zoneOffset | | No longer provided. |
| ns1:defaultTimeZone zoneOffset zoneAbbreviation | `monitoring-locations` | time_zone_abbreviation |
| ns1:daylightSavingsTimeZone zoneOffset | | No longer provided. |
| ns1:daylightSavingsTimeZone zoneOffset zoneAbbreviation | | No longer provided. |
| ns1:geogLocation srs | | No longer provided. All coordinates returned use EPSG:4326 as their CRS, unless you specify an alternative CRS in your query. |
| ns1:geogLocation latitude | `/continuous` | Provided as part of the geometry field. |
| ns1:geogLocation longitude | `/continuous` | Provided as part of the geometry field. |
| ns1:siteProperty name="siteTypeCd" | `/monitoring-locations` | site_type_code |
| ns1:siteProperty name="hucCd" | `/monitoring-locations` | hydrologic_unit_code |
| ns1:siteProperty name="stateCd" | `/monitoring-locations` | state_code |
| ns1:siteProperty name="countyCd" | `/monitoring-locations` | county_code | 
| ns1:variable ns1:oid | | No longer provided. | 
| ns1:variableCode network | | No longer provided. |
| ns1:variableCode vocabulary | | No longer provided. |
| ns1:variableCode default | | No longer provided. |
| ns1:variableCode variableID | | No longer provided. |
| ns1:variableCode | `/continuous`, `/time-series-metadata` | parameter_code |
| ns1:variableName | `/time-series-metadata` | parameter |
| ns1:variableDescription | `/time-series-metadata` | parameter_description |
| ns1:valueType | | No longer provided. |
| ns1:unitCode | `/continuous`, `/time-series-metadata` | unit_of_measure |
| ns1:option name="Statistic" optionCode | `/continuous`, `/time-series-metadata` | statistic_id |
| ns1:option | `/statistic-codes` | statistic_name |
| ns1:noDataValue | | No longer provided. Missing values are now represented as null values. |
| ns1:value qualifiers | `/continuous` | Approval status (qualifiers "P" and "A") are now called approval_status. All other qualifiers are now called qualifier. |
| ns1:value dateTime | `/continuous` | time |
| ns1:value | `/continuous` | value |
| ns1:qualifier qualifierID | | No longer provided. |
| ns1:qualifier ns1:network | | No longer provided. |
| ns1:qualifier ns1:vocabulary="uv_rmk_cd" | | No longer provided. |
| ns1:qualifierCode | `/continuous` | Approval status (qualifiers "P" and "A") are now called approval_status. All other qualifiers are now called qualifier. |
| ns1:qualifierDescription | | Not currently available. |
| ns1:method | | Not currently available. | 
| ns1:method methodID | | Not currently available. | 
| ns1:methodDescription | | Not currently available. |

</div>

## Migrating from /dv to /daily

Daily data provide one data value to represent water conditions for the day. Throughout much of the history of the USGS, the primary water data available were daily data. These data were originally collected manually at the monitoring location each day, then transitioned to being recorded at the location. With improved availability of computer storage and automated transmission of data, the daily data published today are generally a summary statistic or single metric of the continuous data collected each day.

These data were previously available from the `/dv` endpoint on WaterServices, and are now returned by the `/daily` endpoint on the USGS Water Data APIs. To get just the most recent daily value for each time series in the USGS network, use the `/latest-daily` endpoint. 

### 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](https://waterdata.usgs.gov/provisional-data-statement/).

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.

<div class="usa-table-container" tabindex="0">

| Field in the `/dv` "sourceInfo" block | Corresponding field in the `/monitoring-locations` response |
| ------------------------------------- | -------------------------------------------- |
| siteName                              | monitoring_location_name                                             |
| siteCode -> value                | monitoring_location_number . Included in the monitoring_location_id field in `/daily`. |
| siteCode -> agencyCode                | agency_code ("network" is no longer provided). Included in the monitoring_location_id field in `/daily`. |
| timeZoneInfo -> defaultTimeZone -> zoneOffset | No longer provided. |
| timeZoneInfo -> defaultTimeZone -> zoneAbbreviation | time_zone_abbreviation |
| timeZoneInfo -> daylightSavingsTimeZone -> zoneOffset | No longer provided. |
| timeZoneInfo -> daylightSavingsTimeZone -> zoneAbbreviation | No longer provided. |
| timeZoneInfo -> siteUsesDaylightSavingsTime | uses_daylight_savings |
| geoLocation -> geogLocation -> srs | All coordinates are in EPSG:4326, or use the CRS specified by the `crs` argument. |
| geoLocation -> geogLocation -> latitude | Provided as part of the "geometry" object. |
| geoLocation -> geogLocation -> longitude | Provided as part of the "geometry" object. |
| geoLocation -> localSiteXY | No longer provided. |
| note | No longer provided. |
| siteType | site_type |
| siteProperty -> "siteTypeCd" | site_type_code |
| siteProperty -> "hucCd" | hydrologic_unit_code |
| siteProperty -> "stateCd" | state_code |
| siteProperty -> "countyCd" | county_code |

</div>

Certain portions of the "variable" block are now provided by the `/time-series-metadata` and `/statistic-codes` endpoints. 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.

<div class="usa-table-container" tabindex="0">

| Field in the `/dv` "variable" block | Corresponding field in the `/daily` response |
| ------------------------------------- | -------------------------------------------- |
| variableCode -> value | parameter_code |
| variableCode -> network | No longer provided. |
| variableCode -> vocabulary | No longer provided. | 
| variableCode -> variableID | No longer provided. | 
| variableCode -> default | No longer provided. | 
| variableName | parameter in `/time-series-metadata` | 
| variableDescription | parameter_description in `/time-series-metadata` |
| valueType | Not longer provided. |
| unit -> unitCode | unit_of_measure | 
| options -> option -> value | id in `/statistic-codes`. |
| options -> option -> name | No longer provided. | 
| options -> option -> optionCode | statistic_id | 
| note | No longer provided. |
| noDataValue | No longer provided. Missing data is now represented with null values. | 
| variableProperty | No longer provided. |
| oid | No longer provided. | 

</div>

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

<div class="usa-table-container" tabindex="0">

| Field in the `/dv` "values" block | Corresponding field in the `/daily` response |
| ------------------------------------- | -------------------------------------------- |
| value -> value | value |
| value -> qualifiers | approval_status |
| value -> dateTime | time (now an ISO8601 YYYY-MM-DD date string) |
| qualifier -> qualifierCode | Approval status ("Approved" and "Provisional") are now called approval_status. Other qualifiers are called qualifier. |
| qualifier -> qualifierDescription | Not currently available. |
| qualifier -> qualifierID | Not currently available. | 
| qualifier -> network | No longer provided. |
| qualifier -> vocabulary | No longer provided. | 
| qualityControlLevel | No longer provided. |
| method -> methodDescription | Not currently available. | 
| method -> methodID | Not currently available. | 
| source | No longer provided. | 
| offset | No longer provided. | 
| sample | No longer provided. | 
| censorCode | No longer provided. | 

</div>

### 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](https://waterdata.usgs.gov/provisional-data-statement/).

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](https://api.waterdata.usgs.gov/ogcapi/v1/collections/daily/schema) or the [OpenAPI documentation](https://api.waterdata.usgs.gov/ogcapi/v1/openapi?f=html#/daily/getDailyFeatures).

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 now called "parent_time_series_id" in the `/time-series-metadata` endpoint.
- "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", the monitoring location number, is now returned as a value in the "monitoring_location_id" field of the `/daily` endpoint.
- "00060", the parameter code, is now returned as a value in the "parameter_code" field of the `/daily` endpoint.
- "00003", the statistic identifier, 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.

<div class="usa-table-container" tabindex="0">

| Key in the `/dv` WaterML2 response | New endpoint | Corresponding field name |
| ---------------------------------- | ------------ | ------------------------ |
| ns1:timeSeries name | `/monitoring-locations`, `/daily`, `/time-series-metadata` | This name object combines the agency_code and monitoring_location_number from the `/monitoring-locations` endpoint with the parameter_code and statistic_id returned by both the `/daily` and `/time-series-metadata` endpoints. The agency code and monitoring location number are also combined to form the monitoring_location_id in `/daily` and `/time-series-metadata` and the id field in `/monitoring-locations`.|
| ns1:siteName | `/monitoring-locations` | monitoring_location_name |
| ns1:siteCode | `/monitoring-locations` | monitoring_location_number |
| ns1:siteCode network | | No longer provided. | 
| ns1:siteCode agencyCode | `/monitoring-locations` | agency_code. The agency code and monitoring location number are combined to form the monitoring_location_id in `/daily` and `/time-series-metadata` and the id field in `/monitoring-locations`. |
| ns1:timeZoneInfo siteUsesDaylightSavingsTime | `monitoring-locations` | uses_daylight_savings |
| ns1:defaultTimeZone zoneOffset | | No longer provided. |
| ns1:defaultTimeZone zoneOffset zoneAbbreviation | `monitoring-locations` | time_zone_abbreviation |
| ns1:daylightSavingsTimeZone zoneOffset | | No longer provided. |
| ns1:daylightSavingsTimeZone zoneOffset zoneAbbreviation | | No longer provided. |
| ns1:geogLocation srs | | No longer provided. All coordinates returned use EPSG:4326 as their CRS, unless you specify an alternative CRS in your query. |
| ns1:geogLocation latitude | `/daily` | Provided as part of the geometry field. |
| ns1:geogLocation longitude | `/daily` | Provided as part of the geometry field. |
| ns1:siteProperty name="siteTypeCd" | `/monitoring-locations` | site_type_code |
| ns1:siteProperty name="hucCd" | `/monitoring-locations` | hydrologic_unit_code |
| ns1:siteProperty name="stateCd" | `/monitoring-locations` | state_code |
| ns1:siteProperty name="countyCd" | `/monitoring-locations` | county_code | 
| ns1:variable ns1:oid | | No longer provided. | 
| ns1:variableCode network | | No longer provided. |
| ns1:variableCode vocabulary | | No longer provided. |
| ns1:variableCode default | | No longer provided. |
| ns1:variableCode variableID | | No longer provided. |
| ns1:variableCode | `/daily`, `/time-series-metadata` | parameter_code |
| ns1:variableName | `/time-series-metadata` | parameter |
| ns1:variableDescription | `/time-series-metadata` | parameter_description |
| ns1:valueType | | No longer provided. |
| ns1:unitCode | `/daily`, `/time-series-metadata` | unit_of_measure |
| ns1:option name="Statistic" optionCode | `/daily`, `/time-series-metadata` | statistic_id |
| ns1:option | `/statistic-codes` | statistic_name |
| ns1:noDataValue | | No longer provided. Missing values are now represented as null values. |
| ns1:value qualifiers | `/daily` | Approval status (qualifiers "P" and "A") are now called approval_status. All other qualifiers are now called qualifier. |
| ns1:value dateTime | `/daily` | time |
| ns1:value | `/daily` | value |
| ns1:qualifier qualifierID | | No longer provided. |
| ns1:qualifier ns1:network | | No longer provided. |
| ns1:qualifier ns1:vocabulary="uv_rmk_cd" | | No longer provided. |
| ns1:qualifierCode | `/daily` | Approval status (qualifiers "P" and "A") are now called approval_status. All other qualifiers are now called qualifier. |
| ns1:qualifierDescription | | Not currently available. |
| ns1:method | | Not currently available. | 
| ns1:method methodID | | Not currently available. | 
| ns1:methodDescription | | Not currently available. |

</div>

## 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. 

<div class="usa-table-container" tabindex="0">

| Field name in the `/site` endpoint | Field name in the `/monitoring-locations` endpoint | 
| ---------------------------------- | -------------------------------------------------- |
| agency_cd | agency_code |
| site_no | monitoring_location_number | 
| station_nm | monitoring_location_name | 
| site_tp_cd | site_type_code |
| lat_va | No longer provided. |
| long_va | No longer provided. |
| dec_lat_va | Provided as part of "geometry" | 
| dec_long_va | Provided as part of "geometry" | 
| coord_meth_cd | horizontal_position_method_code |
| coord_acy_cd | horizontal_positional_accuracy |
| coord_datum_cd | original_horizontal_datum | 
| dec_coord_datum_cd | No longer provided. |
| district_cd | district_code |
| state_cd | state_code |
| county_cd | county_code |
| country_cd | country_code |
| land_net_ds | No longer provided. |
| map_nm | No longer provided. |
| map_scale_fc | No longer provided. | 
| alt_va | altitude |
| alt_meth_cd | altitude_method_code |
| alt_acy_va | altitude_accuracy |
| alt_datum_cd | vertical_datum |
| huc_cd | hydrologic_unit_code |
| basin_cd | basin_code |
| topo_cd | No longer provided. | 
| instruments_cd | No longer provided. |
| construction_dt | construction_date |
| inventory_dt | No longer provided. |
| drain_area_va | drainage_area |
| contrib_drain_area_va | contributing_drainage_area |
| tz_cd | time_zone_abbreviation |
| local_time_fg | uses_daylight_savings |
| reliability_cd | No longer provided. |
| gw_file_cd | No longer provided. |
| nat_aqfr_cd | national_aquifer_code |
| aqfr_cd | aquifer_code |
| aqfr_type_cd | aquifer_type_code |
| well_depth_va | well_constructed_depth |
| hole_depth_va | hole_constructed_depth |
| depth_src_cd | depth_source_code |
| project_no | No longer provided. |

</div>

## 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.

<div class="usa-table-container" tabindex="0">

| Field name in the `/site` endpoint | Field name in the `/monitoring-locations` endpoint | 
| ---------------------------------- | -------------------------------------------------- |
| agency_cd | agency_code |
| site_no | monitoring_location_number | 
| station_nm | monitoring_location_name | 
| site_tp_cd | site_type_code |
| dec_lat_va | Provided as part of "geometry" | 
| dec_long_va | Provided as part of "geometry" | 
| coord_meth_cd | horizontal_position_method_code |
| coord_acy_cd | horizontal_positional_accuracy |
| coord_datum_cd | original_horizontal_datum | 
| dec_coord_datum_cd | Coordinates are now always in EPSG:4326 unless queries provide a "crs" argument. |
| alt_va | altitude |
| alt_acy_va | altitude_accuracy |
| alt_datum_cd | vertical_datum |
| huc_cd | hydrologic_unit_code |

</div>

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](https://api.waterdata.usgs.gov/samples-data/docs#/summaries/read_summaries_samples_data_summary__monitoringLocationIdentifier__get). 

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.

<div class="usa-table-container" tabindex="0">

| Field name in the `/site` endpoint | Field name in the `/time-series-metadata` endpoint | 
| ---------------------------------- | -------------------------------------------------- |
| data_type_cd | No longer provided. Continuous measurements have a "computation_identifier" of "Instantaneous" and a "computation_period_identifier" of "Points", while daily values have a "computation_period_identifier" of "Daily". |
| parm_cd | parameter_code |
| stat_cd | statistic_id | 
| ts_id | id | 
| loc_web_ds | No longer provided. |
| medium_grp_cd | Not currently available. 
| parm_grp_cd | Not currently available. |
| srs_id | No longer provided. |
| access_cd | No longer provided. |
| begin_date | start |
| end_date | end |
| count_nu | Not currently available. |

</div>

## Migrating from `/gwlevels` to `/field-measurements`

The `/gwlevels` endpoint provided discrete measurements of groundwater levels manually collected by technicians during visits to a monitoring location. This data is now available from the `/field-measurements` endpoint, alongside field measurements of stream discharge and gage height. For continuous measurements of groundwater levels, see the forthcoming `/continuous` endpoint. For daily values of groundwater levels, see the `/daily` endpoint.

### 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 "note" block inside the top-level "value" key will no longer be returned. The "requestDT" has an equivalent in the "timeStamp" field of the `/field-measurements` response object. [The provisional data statement may be accessed at this link](https://waterdata.usgs.gov/provisional-data-statement/).

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" field in the `/field-measurements` endpoint, followed by "00000". The other three blocks are represented in one of the below tables. Note that the `/field-measurements` 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.

<div class="usa-table-container" tabindex="0">

| Field in the `/gwlevels` "sourceInfo" block | Corresponding field in the `/monitoring-locations` response |
| ------------------------------------- | -------------------------------------------- |
| siteName                              | monitoring_location_name                                             |
| siteCode -> value                | monitoring_location_number . Included in the monitoring_location_id field in `/field-measurements`. |
| siteCode -> network                | No longer provided. |
| siteCode -> agencyCode                | agency_code ("network" is no longer provided). Included in the monitoring_location_id field in `/field-measurements`. |
| timeZoneInfo -> defaultTimeZone -> zoneOffset | No longer provided. Measurement timestamps now include time zone information. |
| timeZoneInfo -> defaultTimeZone -> zoneAbbreviation | time_zone_abbreviation |
| timeZoneInfo -> daylightSavingsTimeZone -> zoneOffset | No longer provided. Measurement timestamps now include time zone information. |
| timeZoneInfo -> daylightSavingsTimeZone -> zoneAbbreviation | No longer provided. |
| timeZoneInfo -> siteUsesDaylightSavingsTime | uses_daylight_savings |
| geoLocation -> geogLocation -> srs | All coordinates are in EPSG:4326, or use the CRS specified by the `crs` argument. |
| geoLocation -> geogLocation -> latitude | Provided as part of the "geometry" object. |
| geoLocation -> geogLocation -> longitude | Provided as part of the "geometry" object. |
| geoLocation -> localSiteXY | No longer provided. |
| note | No longer provided. | 
| siteType | site_type |
| siteProperty -> siteTypeCd | site_type_code |
| siteProperty -> hucCd | hydrologic_unit_code |
| siteProperty -> stateCd | state_code |
| siteProperty -> countyCd | county_code |

</div>

Certain portions of the "variable" block are now provided by the `/parameter-codes` endpoint. These are specifically mentioned in the table below.

<div class="usa-table-container" tabindex="0">

| Field in the `/gwlevels` "variable" block | Corresponding field in the `/field-measurements` response |
| ------------------------------------- | -------------------------------------------- |
| variableCode -> value | parameter_code ("id" in `/parameter-codes`) |
| variableCode -> network | No longer provided. |
| variableCode -> vocabulary | No longer provided. | 
| variableCode -> variableID | No longer provided. | 
| variableCode -> default | No longer provided. | 
| variableName | parameter_name in `/parameter-codes` | 
| variableDescription | parameter_description in `/parameter-codes` |
| valueType | Not currently available. |
| unit -> unitCode | unit_of_measure | 
| options -> option -> value | No longer provided (always 00000). |
| options -> option -> name | No longer provided. | 
| options -> option -> optionCode | statistic_id | 
| note | No longer provided. |
| noDataValue | No longer provided. Missing data is now represented with null values. | 
| variableProperty | No longer provided. |
| oid | No longer provided. | 

</div>

Fields in the "values" block are provided by the `/field-measurements` endpoint.

<div class="usa-table-container" tabindex="0">

| Field in the `/gwlevels` "values" block | Corresponding field in the `/field-measurements` response |
| ------------------------------------- | -------------------------------------------- |
| value -> value | value |
| value -> qualifiers | Approval status ("Approved" and "Provisional") are now called approval_status. Other qualifiers are called qualifier. |
| value -> dateTime | time (now an ISO8601 datetime string) |
| qualifier -> qualifierCode | No longer used; approval status and qualifiers now use full words. |
| qualifier -> qualifierDescription | Approval status ("Approved" and "Provisional") are now called approval_status. Other qualifiers are called qualifier. |
| qualifier -> qualifierID | No longer provided. | 
| qualifier -> network | No longer provided. |
| qualifier -> vocabulary | No longer provided. | 
| qualityControlLevel | No longer provided. |
| method -> methodDescription | Not currently available. | 
| method -> methodID | Not currently available. | 
| source | No longer provided. | 
| offset | No longer provided. | 
| sample | No longer provided. | 
| censorCode | No longer provided. | 

</div>

## Migrating from `/measurements` to `/field-measurements`

The `/measurements` webpage provided discrete measurements of discharge and gage height manually collected by technicians during visits to a monitoring location. This data is now available from the `/field-measurements` endpoint, alongside field measurements of groundwater levels. Channel metadata previously available from the "expanded" table are now served from the `/channel-measurements` endpoint.

For continuous measurements of groundwater levels, see the `/continuous` endpoint. For daily values of groundwater levels, see the `/daily` endpoint.

Each measurement taken during a field measurement is now published as a distinct record from the `/field-measurements` service. The new field_visit_id field can be used to identify multiple measurements taken within a single field visit, in order to identify corresponding discharge and gage height measurements.

<div class="usa-table-container" tabindex="0">

| Field in `/measurements` HTML table | Field in `/measurements` tab separated file | Field in `/field-measurements` | Field in `/channel-measurements` |
| ----------------------------------- | ------------------------------------------- | ------------------------------ | -------------------------------- |
| Meas. Number | measurement_nu | | measurement_number |
| Date Time | measurement_dt | time | time |
| Time Datum | tz_cd | No longer provided. The time field contains time zone information. | | 
| Measurement Used? | q_meas_used_fg | No longer provided. All published measurements have a value of "yes". | |
| Who | party_nm | No longer provided. | |
| Measuring Agency | site_visit_coll_agency_cd | measuring_agency | |
| Stream flow (ft³/s) | discharge_va | value | |
| Gage Height (ft) | gage_height_va | value | |
| GH Change (ft) | gage_va_change | Not currently provided. | |
| Meas. Duration (hr) | gage_va_time | Not currently provided. | |
| Meas. Rated | measured_rating_diff | measurement_rated | |
| Control | control_type_cd | control_condition | |
| Flow Adjust. Code | discharge_cd | Not currently provided. | |
| Channel Number | chan_nu | No longer provided. | |
| Channel Name | chan_name | | channel_name |
| Meas. type | meas_type | | measurement_type |
| Stream flow method | streamflow_method | observing_procedure | |
| Velocity method | velocity_method | observing_procedure | |
| Channel flow (ft3/s) | chan_discharge | | channel_flow |
| Channel width | chan_width | | channel_width |
| Channel area (ft2) | chan_area | | channel_area |
| Channel vel. (ft/s) | chan_velocity | | channel_velocity |
| Channel stability | chan_stability | | channel_stability |
| Channel material | chan_material | | channel_material |
| Channel evenness | chan_evenness | | channel_evenness |
| Long. vel. desc. | long_vel_desc | | longitudinal_velocity_description |
| Horiz. vel. desc. | horz_vel_desc | | horizontal_velocity_description |
| Channel loc. code | chan_loc_cd | | channel_location_direction |
| Channel loc. dist.(ft) | chan_loc_dist | | channel_location_distance | 
| | agency_cd | Part of monitoring_location_id | Part of monitoring_location_id |
| | site_no | Part of monitoring_location_id | Part of monitoring_location_id |
| | vert_vel_desc | | vertical_velocity_description |

</div>

## Migrating from `/peak` to `/peaks`

The NWISWeb peaks page (at [https​://waterdata.usgs.gov/nwis/peak](https​://waterdata.usgs.gov/nwis/peak)) provided annual peak streamflow and gage height data for monitoring locations. This data is now available from the `/peaks` endpoint.

In NWISWeb, peak discharge and gage height were returned as columns in the same row. In the new `/peaks` endpoint, each parameter (discharge and gage height) is returned as a separate feature, identified by its `parameter_code` (00060 for discharge, 00065 for gage height).

<div class="usa-table-container--scrollable" tabindex="0">

| Field in `/peak` HTML table | Field in `peak` tab-separated file | Field in `/peaks` endpoint |
| --------------------------- | -------------------------- | -------------------------------------------- |
| | agency_cd | Part of monitoring_location_id |
| | site_no | Part of monitoring_location_id |
| Water Year | | water_year |
| Date | peak_dt | time |
| | peak_tm | time_of_day |
| Stream-flow (cfs) | peak_va | value |
| Peak Streamflow Qualification Codes| peak_cd | qualifier |
| Gage Height (feet) | gage_ht | value |
| Peak Gage-Height Qualification Codes | gage_ht_cd | qualifier |
| | year_last_pk | peak_since |
| | ag_dt | time |
| | ag_tm | time_of_day |
| | ag_gage_ht | value |
| | ag_gage_ht_cd | qualifier |

</div>

### Qualifier code mapping

In NWISWeb, peak qualifiers were represented as short numeric or letter codes. In the new `/peaks` endpoint, these have been replaced with descriptive strings. The table below maps the old peak discharge qualification codes (peak_cd) to their new values:

<div class="usa-table-container--scrollable" tabindex="0">

| peak_cd | Description | WDFN qualifier |
| ------------ | ------------------- | -------------------- |
| 1 | Discharge is a Maximum Daily Average | MAXDAILYMEAN |
| 2 | Discharge is an Estimate | ESTIMATED |
| 3 | Discharge affected by Dam Failure | DAMFAILURE |
| 4 | Discharge less than indicated value, which is Minimum Recordable Discharge at this site | LESSTHAN |
| 5 | Discharge affected to unknown degree by Regulation or Diversion | UNKNOWNREGULATION |
| 6 | Discharge affected by Regulation or Diversion | REGULATED |
| 7 | Discharge is an Historic Peak | HISTORIC |
| 8 | Discharge actually greater than indicated value | GREATERTHAN |
| 9 | Discharge due to Snowmelt, Hurricane, Ice-Jam or Debris Dam breakup | EVENT |
| A | Year of occurrence is unknown or not exact | YEARUNKNOWN |
| Bd | Day of occurrence is unknown or not exact | DAYUNKNOWN |
| Bm | Month of occurrence is unknown or not exact | MONTHUNKNOWN |
| C | All or part of the record affected by Urbanization, Mining, Agricultural changes, Channelization, or other | URBAN |
| F | Peak supplied by another agency | OTHERAGENCY |
| O | Opportunistic value not from systematic data collection | OPPORTUNISTIC |
| R | Revised | REVISED |

</div>

The following table maps the old gage height qualification codes (gage_ht_cd) to their new values:

<div class="usa-table-container--scrollable" tabindex="0">

| gage_ht_cd | Description | WDFN qualifier |
| ------------ | ------------------- | -------------------- |
| 1 | Gage height affected by backwater | BACKWATER |
| 2 | Gage height not the maximum for the year | NOTMAXGH |
| 3 | Gage height at different site and(or) datum | DIFFDATUM |
| 4 | Gage height below minimum recordable elevation | BLWMIN |
| 5 | Gage height is an estimate | ESTIMATED |
| 6 | Gage datum changed during this year | DATUMCHANGE |
| 7 | Debris, mud, or hyper-concentrated flow | DEBRIS |
| 8 | Gage height tidally affected | TIDE |
| Bd | Day of occurrence is unknown or not exact | DAYUNKNOWN |
| Bm | Month of occurrence is unknown or not exact | MONTHUNKNOWN |
| F | Peak supplied by another agency | OTHERAGENCY |
| R | Revised | REVISED |
| N | Max gage height not associated with peak discharge | GHNOTASSCPKQ |

</div>

## 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.