Water Data APIs

Water Data APIs
Official websites use .gov
.gov
website belongs to an official government
organization in the United States.
Secure .gov websites use HTTPS
lock
) or
means you’ve safely connected to
the .gov website. Share sensitive information only on official,
secure websites.
Migrating to modernized APIs
Page contents
Migrating from /iv to /continuous
From WaterServices JSON
From WaterServices RDB
From WaterServices WaterML2
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
Migrating from /gwlevels to /field-measurements
Migrating from /measurements to /field-measurements
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...
Then you should use...
Latest automated measurements from https​://waterservices.usgs.gov/nwis/iv/?
Historical automated measurements from https​://waterservices.usgs.gov/nwis/iv/?
https​://waterservices.usgs.gov/nwis/dv/?
Discharge and gage height readings from https​://waterdata.usgs.gov/measurements/
Channel measurements from https​://waterdata.usgs.gov/measurements/
https​://waterservices.usgs.gov/nwis/gwlevels/
Monitoring location metadata from https​://waterservices.usgs.gov/nwis/site/?
Period of record information from https​://waterservices.usgs.gov/nwis/site/?
If you were using
, you should look at
the documentation for the statistics API
. If you were using
, you should look at
the documentation for the samples-data API
The new APIs listed in the table are all hosted on
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 /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
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.
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
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.
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.
Fields in the "values" block are provided by the
/continuous
endpoint.
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.
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
/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
or the
OpenAPI documentation
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.
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.
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
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.
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
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.
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.
Fields in the "values" block are provided by the
/daily
endpoint.
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.
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 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.
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.
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.
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.
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.
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
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.
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.
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
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.
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
Certain portions of the "variable" block are now provided by the
/parameter-codes
endpoint. These are specifically mentioned in the table below.
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.
Fields in the "values" block are provided by the
/field-measurements
endpoint.
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.
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.
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
Not currently provided.
Control
control_type_cd
Not currently provided.
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
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.