USGS Water Services combined-metadata API
This endpoint combines metadata from timeseries and field measurements collections by site.
OpenAPI Specification
openapi: 3.0.2
info:
contact:
name: US Geological Survey - Water Data for the Nation
url: https://waterdata.usgs.gov
x-ogc-serviceContact:
addresses: []
emails:
- value: wdfn@usgs.gov
hoursOfService: pointOfContact
links:
- href: https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov
type: text/html
name: WDFN Support
description: 'These APIs provide OGC-compliant interfaces to USGS water data, letting you download continuous sensor measurements, discrete field measurements, metadata about monitoring locations, and more.
'
license:
name: US Government work in the public domain
url: https://creativecommons.org/publicdomain/zero/1.0/
termsOfService: https://creativecommons.org/publicdomain/zero/1.0/
title: USGS Water Data OGC APIs agency-codes combined-metadata API
version: 0.56.0
x-keywords:
- geospatial
- data
- api
- hydrology
- USGS
servers:
- description: 'These APIs provide OGC-compliant interfaces to USGS water data, letting you download continuous sensor measurements, discrete field measurements, metadata about monitoring locations, and more.
'
url: https://api.waterdata.usgs.gov/ogcapi/v0
tags:
- description: 'This endpoint combines metadata from timeseries and field measurements collections by site.
'
name: combined-metadata
paths:
/collections/combined-metadata:
get:
description: 'This endpoint combines metadata from timeseries and field measurements collections by site.
'
operationId: describeCombined-metadataCollection
parameters:
- $ref: '#/components/parameters/f'
- $ref: '#/components/parameters/lang'
responses:
'200':
$ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/Collection
'400':
$ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/InvalidParameter
'403':
$ref: '#/components/responses/Forbidden403'
'404':
$ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/NotFound
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/ServerError
summary: Get Combined metadata metadata
tags:
- combined-metadata
/collections/combined-metadata/items:
get:
description: 'This endpoint combines metadata from timeseries and field measurements collections by site.
'
operationId: getCombined-metadataFeatures
parameters:
- description: The optional f parameter indicates the output format which the server shall provide as part of the response document. The default format is GeoJSON.
explode: false
in: query
name: f
required: false
schema:
default: json
enum:
- json
- html
- jsonld
- csv
type: string
style: form
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/bbox'
- description: The optional limit parameter limits the number of items that are presented in the response document (maximum=50000, default=10).
explode: false
in: query
name: limit
required: false
schema:
default: 10
maximum: 50000
minimum: 1
type: integer
style: form
- $ref: '#/components/parameters/crs'
- $ref: '#/components/parameters/bbox-crs'
- description: The properties that should be included. The parameter value is a comma-separated list of property names.
explode: false
in: query
name: properties
required: false
schema:
items:
enum:
- monitoring_location_id
- agency_code
- agency_name
- monitoring_location_number
- monitoring_location_name
- district_code
- country_code
- country_name
- state_code
- state_name
- county_code
- county_name
- minor_civil_division_code
- site_type_code
- site_type
- hydrologic_unit_code
- basin_code
- altitude
- altitude_accuracy
- altitude_method_code
- altitude_method_name
- vertical_datum
- vertical_datum_name
- horizontal_positional_accuracy_code
- horizontal_positional_accuracy
- horizontal_position_method_code
- horizontal_position_method_name
- original_horizontal_datum
- original_horizontal_datum_name
- drainage_area
- contributing_drainage_area
- time_zone_abbreviation
- uses_daylight_savings
- construction_date
- aquifer_code
- national_aquifer_code
- aquifer_type_code
- well_constructed_depth
- hole_constructed_depth
- depth_source_code
- id
- unit_of_measure
- parameter_name
- parameter_code
- statistic_id
- last_modified
- begin
- end
- data_type
- computation_identifier
- thresholds
- sublocation_identifier
- primary
- web_description
- parameter_description
- parent_time_series_id
type: string
type: array
style: form
- $ref: '#/components/parameters/skipGeometry'
- $ref: '#/components/parameters/wda_sortby'
- $ref: '#/components/parameters/offset'
- description: "A unique identifier representing a single monitoring location. This corresponds to the `id` field in the `monitoring-locations` endpoint. Monitoring location IDs are created by combining the agency code of the agency responsible for the monitoring location (e.g. USGS) with the ID number of the monitoring location (e.g. 02238500), separated by a hyphen (e.g. USGS-02238500).\n Split parameters are enabled for this field, so you can supply multiple values separated by commas."
explode: false
in: query
name: monitoring_location_id
required: false
schema:
description: "A unique identifier representing a single monitoring location. This corresponds to the `id` field in the `monitoring-locations` endpoint. Monitoring location IDs are created by combining the agency code of the agency responsible for the monitoring location (e.g. USGS) with the ID number of the monitoring location (e.g. 02238500), separated by a hyphen (e.g. USGS-02238500).\n Split parameters are enabled for this field, so you can supply multiple values separated by commas."
title: Monitoring location ID
type: string
style: form
- description: 'The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items).
'
explode: false
in: query
name: agency_code
required: false
schema:
description: 'The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items).
'
title: Agency code
type: string
style: form
- description: 'The name of the agency that is reporting the data.
'
explode: false
in: query
name: agency_name
required: false
schema:
description: 'The name of the agency that is reporting the data.
'
title: Agency name
type: string
style: form
- description: 'Each monitoring location in the USGS data base has a unique 8- to 15-digit identification number.
'
explode: false
in: query
name: monitoring_location_number
required: false
schema:
description: 'Each monitoring location in the USGS data base has a unique 8- to 15-digit identification number.
'
title: Monitoring location number
type: string
style: form
- description: 'This is the official name of the monitoring location in the database. For well information this can be a district-assigned local number.
'
explode: false
in: query
name: monitoring_location_name
required: false
schema:
description: 'This is the official name of the monitoring location in the database. For well information this can be a district-assigned local number.
'
title: Monitoring location name
type: string
style: form
- description: 'The Water Science Centers (WSCs) across the United States use the FIPS state code as the district code. In some case, monitoring locations and samples may be managed by a water science center that is adjacent to the state in which the monitoring location actually resides. For example a monitoring location may have a district code of 30 which translates to Montana, but the state code could be 56 for Wyoming because that is where the monitoring location actually is located.
'
explode: false
in: query
name: district_code
required: false
schema:
description: 'The Water Science Centers (WSCs) across the United States use the FIPS state code as the district code. In some case, monitoring locations and samples may be managed by a water science center that is adjacent to the state in which the monitoring location actually resides. For example a monitoring location may have a district code of 30 which translates to Montana, but the state code could be 56 for Wyoming because that is where the monitoring location actually is located.
'
title: District code
type: string
style: form
- description: 'The code for the country in which the monitoring location is located.
'
explode: false
in: query
name: country_code
required: false
schema:
description: 'The code for the country in which the monitoring location is located.
'
title: Country code
type: string
style: form
- description: 'The name of the country in which the monitoring location is located.
'
explode: false
in: query
name: country_name
required: false
schema:
description: 'The name of the country in which the monitoring location is located.
'
title: Country name
type: string
style: form
- description: 'State code. A [two-digit ANSI code](https://www2.census.gov/geo/docs/reference/state.txt) (formerly FIPS code) as defined by the American National Standards Institute, to define States and equivalents. A three-digit ANSI code is used to define counties and county equivalents. [A lookup table is available.](https://www.census.gov/library/reference/code-lists/ansi.html#states) The only countries with political subdivisions other than the US are Mexico and Canada. The Mexican states have US state codes ranging from 81-86 and Canadian provinces have state codes ranging from 90-98.
'
explode: false
in: query
name: state_code
required: false
schema:
description: 'State code. A [two-digit ANSI code](https://www2.census.gov/geo/docs/reference/state.txt) (formerly FIPS code) as defined by the American National Standards Institute, to define States and equivalents. A three-digit ANSI code is used to define counties and county equivalents. [A lookup table is available.](https://www.census.gov/library/reference/code-lists/ansi.html#states) The only countries with political subdivisions other than the US are Mexico and Canada. The Mexican states have US state codes ranging from 81-86 and Canadian provinces have state codes ranging from 90-98.
'
title: State code
type: string
style: form
- description: 'The name of the state or state equivalent in which the monitoring location is located.
'
explode: false
in: query
name: state_name
required: false
schema:
description: 'The name of the state or state equivalent in which the monitoring location is located.
'
title: State name
type: string
style: form
- description: 'The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items).
'
explode: false
in: query
name: county_code
required: false
schema:
description: 'The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items).
'
title: County code
type: string
style: form
- description: 'The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items).
'
explode: false
in: query
name: county_name
required: false
schema:
description: 'The name of the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. [A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items).
'
title: County name
type: string
style: form
- description: 'Codes for primary governmental or administrative divisions of the county or county equivalent in which the monitoring location is located.
'
explode: false
in: query
name: minor_civil_division_code
required: false
schema:
description: 'Codes for primary governmental or administrative divisions of the county or county equivalent in which the monitoring location is located.
'
title: Minor civil division code
type: string
style: form
- description: 'A code describing the hydrologic setting of the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items).
'
explode: false
in: query
name: site_type_code
required: false
schema:
description: 'A code describing the hydrologic setting of the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items).
'
title: Monitoring location type code
type: string
style: form
- description: 'A description of the hydrologic setting of the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items).
'
explode: false
in: query
name: site_type
required: false
schema:
description: 'A description of the hydrologic setting of the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items).
'
title: Monitoring location type
type: string
style: form
- description: "The United States is divided and sub-divided into successively smaller hydrologic units which are classified into four levels: regions, sub-regions, accounting units, and cataloging units. The hydrologic units are arranged within each other, from the smallest (cataloging units) to the largest (regions). Each hydrologic unit is identified by a unique hydrologic unit code (HUC) consisting of two to eight digits based on the four levels of classification in the hydrologic unit system.\n Search will match partial HUCs."
explode: false
in: query
name: hydrologic_unit_code
required: false
schema:
description: "The United States is divided and sub-divided into successively smaller hydrologic units which are classified into four levels: regions, sub-regions, accounting units, and cataloging units. The hydrologic units are arranged within each other, from the smallest (cataloging units) to the largest (regions). Each hydrologic unit is identified by a unique hydrologic unit code (HUC) consisting of two to eight digits based on the four levels of classification in the hydrologic unit system.\n Search will match partial HUCs."
title: Hydrologic unit code (HUC)
type: string
style: form
- description: 'The Basin Code or "drainage basin code" is a two-digit code that further subdivides the 8-digit hydrologic-unit code. The drainage basin code is defined by the USGS State Office where the monitoring location is located.
'
explode: false
in: query
name: basin_code
required: false
schema:
description: 'The Basin Code or "drainage basin code" is a two-digit code that further subdivides the 8-digit hydrologic-unit code. The drainage basin code is defined by the USGS State Office where the monitoring location is located.
'
title: Basin code
type: string
style: form
- description: 'Altitude of the monitoring location referenced to the specified Vertical Datum.
'
explode: false
in: query
name: altitude
required: false
schema:
description: 'Altitude of the monitoring location referenced to the specified Vertical Datum.
'
title: Altitude
type: number
style: form
- description: 'Accuracy of the altitude, in feet. An accuracy of +/- 0.1 foot would be entered as “.1”. Many altitudes are interpolated from the contours on topographic maps; accuracies determined in this way are generally entered as one-half of the contour interval.
'
explode: false
in: query
name: altitude_accuracy
required: false
schema:
description: 'Accuracy of the altitude, in feet. An accuracy of +/- 0.1 foot would be entered as “.1”. Many altitudes are interpolated from the contours on topographic maps; accuracies determined in this way are generally entered as one-half of the contour interval.
'
title: Altitude accuracy
type: number
style: form
- description: 'Codes representing the method used to measure altitude.
'
explode: false
in: query
name: altitude_method_code
required: false
schema:
description: 'Codes representing the method used to measure altitude.
'
title: Altitude method code
type: string
style: form
- description: 'The name of the method used to measure altitude.
'
explode: false
in: query
name: altitude_method_name
required: false
schema:
description: 'The name of the method used to measure altitude.
'
title: Altitude method name
type: string
style: form
- description: 'The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items).
'
explode: false
in: query
name: vertical_datum
required: false
schema:
description: 'The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items).
'
title: Vertical datum
type: string
style: form
- description: 'The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items).
'
explode: false
in: query
name: vertical_datum_name
required: false
schema:
description: 'The datum used to determine altitude and vertical position at the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/altitude-datums/items).
'
title: Vertical datum name
type: string
style: form
- description: 'Indicates the accuracy of the latitude longitude values. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items).
'
explode: false
in: query
name: horizontal_positional_accuracy_code
required: false
schema:
description: 'Indicates the accuracy of the latitude longitude values. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items).
'
title: Horizontal positional accuracy code
type: string
style: form
- description: 'Indicates the accuracy of the latitude longitude values. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items).
'
explode: false
in: query
name: horizontal_positional_accuracy
required: false
schema:
description: 'Indicates the accuracy of the latitude longitude values. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-accuracy-codes/items).
'
title: Horizontal positional accuracy
type: string
style: form
- description: 'Indicates the method used to determine latitude longitude values. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items).
'
explode: false
in: query
name: horizontal_position_method_code
required: false
schema:
description: 'Indicates the method used to determine latitude longitude values. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items).
'
title: Horizontal position method code
type: string
style: form
- description: 'Indicates the method used to determine latitude longitude values. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items).
'
explode: false
in: query
name: horizontal_position_method_name
required: false
schema:
description: 'Indicates the method used to determine latitude longitude values. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-method-codes/items).
'
title: Horizontal position method name
type: string
style: form
- description: 'Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items).
'
explode: false
in: query
name: original_horizontal_datum
required: false
schema:
description: 'Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items).
'
title: Original horizontal datum
type: string
style: form
- description: 'Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items).
'
explode: false
in: query
name: original_horizontal_datum_name
required: false
schema:
description: 'Coordinates are published in EPSG:4326 / WGS84 / World Geodetic System 1984. This field indicates the original datum used to determine coordinates before they were converted. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/coordinate-datum-codes/items).
'
title: Original horizontal datum name
type: string
style: form
- description: 'The area enclosed by a topographic divide from which direct surface runoff from precipitation normally drains by gravity into the stream above that point.
'
explode: false
in: query
name: drainage_area
required: false
schema:
description: 'The area enclosed by a topographic divide from which direct surface runoff from precipitation normally drains by gravity into the stream above that point.
'
title: Drainage area
type: number
style: form
- description: 'The contributing drainage area of a lake, stream, wetland, or estuary monitoring location, in square miles. This item should be present only if the contributing area is different from the total drainage area. This situation can occur when part of the drainage area consists of very porous soil or depressions that either allow all runoff to enter the groundwater or traps the water in ponds so that rainfall does not contribute to runoff. A transbasin diversion can also affect the total drainage area.
'
explode: false
in: query
name: contributing_drainage_area
required: false
schema:
description: 'The contributing drainage area of a lake, stream, wetland, or estuary monitoring location, in square miles. This item should be present only if the contributing area is different from the total drainage area. This situation can occur when part of the drainage area consists of very porous soil or depressions that either allow all runoff to enter the groundwater or traps the water in ponds so that rainfall does not contribute to runoff. A transbasin diversion can also affect the total drainage area.
'
title: Contributing drainage area
type: number
style: form
- description: 'A short code describing the time zone used by a monitoring location.
'
explode: false
in: query
name: time_zone_abbreviation
required: false
schema:
description: 'A short code describing the time zone used by a monitoring location.
'
title: Time zone abbreviation
type: string
style: form
- description: 'A flag indicating whether or not a monitoring location uses daylight savings.
'
explode: false
in: query
name: uses_daylight_savings
required: false
schema:
description: 'A flag indicating whether or not a monitoring location uses daylight savings.
'
title: Uses daylight savings flag
type: string
style: form
- description: 'Date the well was completed.
'
explode: false
in: query
name: construction_date
required: false
schema:
description: 'Date the well was completed.
'
title: Construction date
type: string
style: form
- description: 'Local aquifers in the USGS water resources data base are identified by a geohydrologic unit code (a three-digit number related to the age of the formation, followed by a 4 or 5 character abbreviation for the geologic unit or aquifer name).
'
explode: false
in: query
name: aquifer_code
required: false
schema:
description: 'Local aquifers in the USGS water resources data base are identified by a geohydrologic unit code (a three-digit number related to the age of the formation, followed by a 4 or 5 character abbreviation for the geologic unit or aquifer name).
'
title: Aquifer code
type: string
style: form
- description: 'National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all groundwater monitoring locations can be associated with a National Aquifer. Such monitoring locations will not be retrieved using this search criteria. A list of National aquifer codes and names is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/national-aquifer-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/national-aquifer-codes/items).
'
explode: false
in: query
name: national_aquifer_code
required: false
schema:
description: 'National aquifers are the principal aquifers or aquifer systems in the United States, defined as regionally extensive aquifers or aquifer systems that have the potential to be used as a source of potable water. Not all gr
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/usgs-water/refs/heads/main/openapi/usgs-water-combined-metadata-api-openapi.yml