Department of Interior channel-measurements API
Channel measurements taken as part of streamflow field measurements.
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 channel-measurements 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: 'Channel measurements taken as part of streamflow field measurements.
'
name: channel-measurements
paths:
/collections/channel-measurements:
get:
description: 'Channel measurements taken as part of streamflow field measurements.
'
operationId: describeChannel-measurementsCollection
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 Channel measurements metadata
tags:
- channel-measurements
/collections/channel-measurements/items:
get:
description: 'Channel measurements taken as part of streamflow field measurements.
'
operationId: getChannel-measurementsFeatures
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:
- id
- monitoring_location_id
- field_visit_id
- measurement_number
- time
- channel_name
- channel_flow
- channel_flow_unit
- channel_width
- channel_width_unit
- channel_area
- channel_area_unit
- channel_velocity
- channel_velocity_unit
- channel_location_distance
- channel_location_distance_unit
- channel_stability
- channel_material
- channel_evenness
- horizontal_velocity_description
- vertical_velocity_description
- longitudinal_velocity_description
- measurement_type
- last_modified
- channel_measurement_type
- channel_location_direction
type: string
type: array
style: form
- $ref: '#/components/parameters/skipGeometry'
- $ref: '#/components/parameters/wda_sortby'
- $ref: '#/components/parameters/offset'
- $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/parameters/datetime
- description: 'A universally unique identifier (UUID) representing a single version of a record. It is not stable over time. Every time the record is refreshed in our database (which may happen as part of normal operations and does not imply any change to the data itself) a new ID will be generated. To uniquely identify a single observation over time, compare the `time` and `time_series_id` fields; each time series will only have a single observation at a given `time`.
'
explode: false
in: query
name: id
required: false
schema:
description: 'A universally unique identifier (UUID) representing a single version of a record. It is not stable over time. Every time the record is refreshed in our database (which may happen as part of normal operations and does not imply any change to the data itself) a new ID will be generated. To uniquely identify a single observation over time, compare the `time` and `time_series_id` fields; each time series will only have a single observation at a given `time`.
'
format: uuid
title: Record identifier
type: string
style: form
- 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: "A universally unique identifier (UUID) for the field visit. Multiple measurements may be made during a single field visit.\n Split parameters are enabled for this field, so you can supply multiple values separated by commas."
explode: false
in: query
name: field_visit_id
required: false
schema:
description: "A universally unique identifier (UUID) for the field visit. Multiple measurements may be made during a single field visit.\n Split parameters are enabled for this field, so you can supply multiple values separated by commas."
format: uuid
title: Field visit ID
type: string
style: form
- description: Measurement number.
explode: false
in: query
name: measurement_number
required: false
schema:
description: Measurement number.
title: Measurement number
type: string
style: form
- description: "The date an observation represents. You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end).\nExamples:\n\n - A date-time: \"2018-02-12T23:20:50Z\"\n - A bounded interval: \"2018-02-12T00:00:00Z/2018-03-18T12:31:12Z\"\n - Half-bounded intervals: \"2018-02-12T00:00:00Z/..\" or \"../2018-03-18T12:31:12Z\"\n - Duration objects: \"P1M\" for data from the past month or \"PT36H\" for the last 36 hours\n\nOnly features that have a `time` that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.\n"
explode: false
in: query
name: time
required: false
schema:
description: "The date an observation represents. You can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end).\nExamples:\n\n - A date-time: \"2018-02-12T23:20:50Z\"\n - A bounded interval: \"2018-02-12T00:00:00Z/2018-03-18T12:31:12Z\"\n - Half-bounded intervals: \"2018-02-12T00:00:00Z/..\" or \"../2018-03-18T12:31:12Z\"\n - Duration objects: \"P1M\" for data from the past month or \"PT36H\" for the last 36 hours\n\nOnly features that have a `time` that intersects the value of datetime are selected. If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.\n"
title: Time
type: string
style: form
- description: The channel name.
explode: false
in: query
name: channel_name
required: false
schema:
description: The channel name.
title: Channel name
type: string
style: form
- description: Channel discharge.
explode: false
in: query
name: channel_flow
required: false
schema:
description: Channel discharge.
title: Channel flow
type: string
style: form
- description: The units for channel discharge.
explode: false
in: query
name: channel_flow_unit
required: false
schema:
description: The units for channel discharge.
title: Channel flow unit
type: string
style: form
- description: The channel width.
explode: false
in: query
name: channel_width
required: false
schema:
description: The channel width.
title: Channel width
type: string
style: form
- description: The units for channel width.
explode: false
in: query
name: channel_width_unit
required: false
schema:
description: The units for channel width.
title: Channel width unit
type: string
style: form
- description: The channel area.
explode: false
in: query
name: channel_area
required: false
schema:
description: The channel area.
title: Channel area
type: string
style: form
- description: The units for channel area.
explode: false
in: query
name: channel_area_unit
required: false
schema:
description: The units for channel area.
title: Channel area unit
type: string
style: form
- description: The mean channel velocity.
explode: false
in: query
name: channel_velocity
required: false
schema:
description: The mean channel velocity.
title: Channel velocity
type: string
style: form
- description: The units for channel velocity.
explode: false
in: query
name: channel_velocity_unit
required: false
schema:
description: The units for channel velocity.
title: Channel velocity unit
type: string
style: form
- description: The channel location distance.
explode: false
in: query
name: channel_location_distance
required: false
schema:
description: The channel location distance.
title: Channel location distance
type: string
style: form
- description: The units for channel location distance.
explode: false
in: query
name: channel_location_distance_unit
required: false
schema:
description: The units for channel location distance.
title: Channel location distance unit
type: string
style: form
- description: The stability of the channel material.
explode: false
in: query
name: channel_stability
required: false
schema:
description: The stability of the channel material.
title: Channel stability
type: string
style: form
- description: The channel material.
explode: false
in: query
name: channel_material
required: false
schema:
description: The channel material.
title: Channel material
type: string
style: form
- description: The channel evenness from bank to bank.
explode: false
in: query
name: channel_evenness
required: false
schema:
description: The channel evenness from bank to bank.
title: Channel evenness
type: string
style: form
- description: The horizontal velocity description.
explode: false
in: query
name: horizontal_velocity_description
required: false
schema:
description: The horizontal velocity description.
title: Horizontal velocity description
type: string
style: form
- description: The vertical velocity description.
explode: false
in: query
name: vertical_velocity_description
required: false
schema:
description: The vertical velocity description.
title: Vertical velocity description
type: string
style: form
- description: The longitudinal velocity description.
explode: false
in: query
name: longitudinal_velocity_description
required: false
schema:
description: The longitudinal velocity description.
title: Longitudinal velocity description
type: string
style: form
- description: The measurement type.
explode: false
in: query
name: measurement_type
required: false
schema:
description: The measurement type.
title: Measurement type
type: string
style: form
- description: "The last time a record was refreshed in our database. This may happen due to regular operational processes and does not necessarily indicate anything about the measurement has changed.\nYou can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end).\nExamples:\n\n - A date-time: \"2018-02-12T23:20:50Z\"\n - A bounded interval: \"2018-02-12T00:00:00Z/2018-03-18T12:31:12Z\"\n - Half-bounded intervals: \"2018-02-12T00:00:00Z/..\" or \"../2018-03-18T12:31:12Z\"\n - Duration objects: \"P1M\" for data from the past month or \"PT36H\" for the last 36 hours\n\nOnly features that have a `last_modified` that intersects the value of datetime are selected.\n"
explode: false
in: query
name: last_modified
required: false
schema:
description: "The last time a record was refreshed in our database. This may happen due to regular operational processes and does not necessarily indicate anything about the measurement has changed.\nYou can query this field using date-times or intervals, adhering to RFC 3339, or using ISO 8601 duration objects. Intervals may be bounded or half-bounded (double-dots at start or end).\nExamples:\n\n - A date-time: \"2018-02-12T23:20:50Z\"\n - A bounded interval: \"2018-02-12T00:00:00Z/2018-03-18T12:31:12Z\"\n - Half-bounded intervals: \"2018-02-12T00:00:00Z/..\" or \"../2018-03-18T12:31:12Z\"\n - Duration objects: \"P1M\" for data from the past month or \"PT36H\" for the last 36 hours\n\nOnly features that have a `last_modified` that intersects the value of datetime are selected.\n"
title: Last modified date
type: string
style: form
- description: The channel measurement type.
explode: false
in: query
name: channel_measurement_type
required: false
schema:
description: The channel measurement type.
title: Channel measurement type
type: string
style: form
- description: Location of the measurement from the gage.
explode: false
in: query
name: channel_location_direction
required: false
schema:
description: Location of the measurement from the gage.
title: Channel Location Direction
type: string
style: form
- $ref: '#/components/parameters/filter'
responses:
'200':
$ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/Features
'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
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
summary: Get Channel measurements items
tags:
- channel-measurements
options:
description: 'Channel measurements taken as part of streamflow field measurements.
'
operationId: optionsChannel-measurementsFeatures
responses:
'200':
description: options response
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
summary: Options for Channel measurements items
tags:
- channel-measurements
post:
description: 'Channel measurements taken as part of streamflow field measurements.
'
operationId: getCQL2Channel-measurementsFeatures
requestBody:
content:
application/json:
schema:
$ref: https://schemas.opengis.net/cql2/1.0/cql2.json
description: Get items with CQL2
required: true
responses:
'200':
$ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/Features
'400':
$ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/InvalidParameter
'403':
$ref: '#/components/responses/Forbidden403'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/ServerError
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
summary: Get Channel measurements items with CQL2
tags:
- channel-measurements
/collections/channel-measurements/items/{featureId}:
get:
description: 'Channel measurements taken as part of streamflow field measurements.
'
operationId: getChannel-measurementsFeature
parameters:
- $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/parameters/featureId
- $ref: '#/components/parameters/crs'
- $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/Feature
'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
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
summary: Get Channel measurements item by id
tags:
- channel-measurements
options:
description: 'Channel measurements taken as part of streamflow field measurements.
'
operationId: optionsChannel-measurementsFeature
parameters:
- $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/parameters/featureId
responses:
'200':
description: options response
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
summary: Options for Channel measurements item by id
tags:
- channel-measurements
/collections/channel-measurements/queryables:
get:
description: 'Channel measurements taken as part of streamflow field measurements.
'
operationId: getChannel-measurementsQueryables
parameters:
- 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:
- id
- monitoring_location_id
- field_visit_id
- measurement_number
- time
- channel_name
- channel_flow
- channel_flow_unit
- channel_width
- channel_width_unit
- channel_area
- channel_area_unit
- channel_velocity
- channel_velocity_unit
- channel_location_distance
- channel_location_distance_unit
- channel_stability
- channel_material
- channel_evenness
- horizontal_velocity_description
- vertical_velocity_description
- longitudinal_velocity_description
- measurement_type
- last_modified
- channel_measurement_type
- channel_location_direction
type: string
type: array
style: form
- $ref: '#/components/parameters/f'
- description: The profile to be applied to a given request
explode: false
in: query
name: profile
required: false
schema:
enum:
- actual-domain
- valid-domain
type: string
style: form
- $ref: '#/components/parameters/lang'
responses:
'200':
$ref: '#/components/responses/Queryables'
'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
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
summary: Get Channel measurements queryables
tags:
- channel-measurements
/collections/channel-measurements/schema:
get:
description: 'Channel measurements taken as part of streamflow field measurements.
'
operationId: getChannel-measurementsSchema
parameters:
- $ref: '#/components/parameters/f'
- $ref: '#/components/parameters/lang'
responses:
'200':
$ref: '#/components/responses/Queryables'
'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
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
summary: Get Channel measurements schema
tags:
- channel-measurements
components:
parameters:
offset:
description: The optional offset parameter indicates the index within the result set from which the server shall begin presenting results in the response document. The first element has an index of 0 (default).
explode: false
in: query
name: offset
required: false
schema:
default: 0
minimum: 0
type: integer
style: form
skipGeometry:
description: This option can be used to skip response geometries for each feature.
explode: false
in: query
name: skipGeometry
required: false
schema:
default: false
type: boolean
style: form
f:
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. CSV is also available.
explode: false
in: query
name: f
required: false
schema:
default: json
enum:
- json
- html
- jsonld
- csv
type: string
style: form
bbox:
description: Only features that have a geometry that intersects the bounding box are selected.The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or depth).
explode: false
in: query
name: bbox
required: false
schema:
items:
type: number
maxItems: 6
minItems: 4
type: array
style: form
bbox-crs:
description: Indicates the coordinate reference system for the given bbox coordinates.
explode: false
in: query
name: bbox-crs
required: false
schema:
format: uri
type: string
style: form
filter:
description: "CQL Text filter expression. CQL JSON cannot be used here, only in the body. \nSee also: https://docs.pygeoapi.io/en/latest/cql.html \n\nExample: time_series_id IN ('64ee32f5350a4ec4967435dcd2e364ea', '3e55d9c2d8a54bec9ca5e292b07d5a96')"
in: query
name: filter
required: false
schema:
type: string
crs:
description: Indicates the coordinate reference system for the results.
explode: false
in: query
name: crs
required: false
schema:
format: uri
type: string
style: form
wda_sortby:
description: "Specifies a comma-separated list of property names by which the response shall be sorted. If the property name is preceded by a plus (+) sign it indicates an ascending sort for that property. If the property name is preceded by a minus (-) sign it indicates a descending sort for that property. If the property is not preceded by a plus or minus, then the default sort order implied is ascending (+). \n\nOnly a single page of data can be returned when specifying sortby. If you need more than a single page of data, don't specify a sortby value and sort the full data set after it's been downloaded."
explode: false
in: query
name: sortby
required: false
schema:
items:
pattern: '[+|-]?[A-Za-z_].*'
type: string
minItems: 1
type: array
style: form
lang:
description: The optional lang parameter instructs the server return a response in a certain language, if supported. If the language is not among the available values, the Accept-Language header language will be used if it is supported. If the header is missing, the default server language is used. Note that providers may only support a single language (or often no language at all), that can be different from the server language. Language strings can be written in a complex (e.g. "fr-CA,fr;q=0.9,en-US;q=0.8,en;q=0.7"), simple (e.g. "de") or locale-like (e.g. "de-CH" or "fr_BE") fashion.
in: query
name: lang
required: false
schema:
default: en-US
enum:
- en-US
type: string
responses:
TooManyRequests429:
content:
application/json:
examples:
rateLimitExceeded:
summary: Rate Limit Exceeded
value:
error:
code: OVER_RATE_LIMIT
message: You have exceeded your rate limit. Make sure you provided your API key from https://api.waterdata.usgs.gov/signup/, then either try again later or contact us at https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov for assistance.
schema:
$ref: '#/components/schemas/Error'
application/xml:
example: "<response>\n <error>\n <code>OVER_RATE_LIMIT</code>\n <message>You have exceeded your rate limit. Make sure you provided your API key from https://api.waterdata.usgs.gov/signup/, then either try again later or contact us at https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov for assistance.</message>\n </error>\n </response>"
schema:
properties:
response:
properties:
error:
properties:
code:
type: string
message:
type: string
required:
- code
- message
type: object
required:
- error
type: object
type: object
text/csv:
examples:
rateLimitCsv:
summary: Rate Limit Exceeded (CSV)
value: 'Error Code,Error Message
OVER_RATE_LIMIT,You have exceeded your rate limit. Make sure you provided your API key from https://api.waterdata.usgs.gov/signup/, then either try again later or contact us at https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov for assistance.'
schema:
type: string
text/html:
examples:
rateLimitHtml:
summary: Rate Limit Ex
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/doi/refs/heads/main/openapi/doi-channel-measurements-api-openapi.yml