U.S. Geological Survey Collections API

openapi: 3.2.0
info:
  title: USGS Water Data Collections API
  description: The USGS Water Data APIs provide OGC-compliant interfaces to USGS water data, including continuous sensor measurements, daily values, discrete field measurements, and metadata about monitoring locations. These APIs implement the OGC API Features standard and support spatial filtering, temporal filtering, CQL2 filtering, and multiple output formats. An API key is required for data access beyond metadata endpoints.
  version: 0.49.2
  contact:
    name: USGS Water Data for the Nation
    url: https://api.waterdata.usgs.gov/
    email: wdfn@usgs.gov
  license:
    name: Public Domain (CC0 1.0)
    url: https://creativecommons.org/publicdomain/zero/1.0/
  x-generated-from: documentation
servers:
- url: https://api.waterdata.usgs.gov/ogcapi/v0
  description: USGS Water Data OGC API
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
- {}
tags:
- name: Collections
  description: OGC API collections listing and metadata.
paths:
  /:
    get:
      operationId: getLandingPage
      summary: USGS Water Data Get API Landing Page
      description: Retrieve the OGC API landing page with links to available resources, conformance declarations, and API documentation.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Landing page with API links and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LandingPage'
              examples:
                GetLandingPage200Example:
                  summary: Default getLandingPage 200 response
                  x-microcks-default: true
                  value:
                    title: USGS Water Data OGC APIs
                    description: Access to USGS water data using OGC API standards.
                    links:
                    - href: https://api.waterdata.usgs.gov/ogcapi/v0/
                      rel: self
                      type: application/json
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /collections:
    get:
      operationId: listCollections
      summary: USGS Water Data List Collections
      description: List all available OGC API collections (data layers) including monitoring locations, time series, reference codes, and other water data entities.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: List of available collections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionsList'
              examples:
                ListCollections200Example:
                  summary: Default listCollections 200 response
                  x-microcks-default: true
                  value:
                    collections:
                    - id: monitoring-locations
                      title: Monitoring Locations
                      description: USGS water monitoring sites including stream gages and wells.
                    - id: time-series
                      title: Time Series
                      description: Continuous sensor measurement time series.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CollectionsList:
      title: CollectionsList
      type: object
      description: List of available OGC API collections.
      properties:
        collections:
          type: array
          description: Array of collection metadata objects.
          items:
            $ref: '#/components/schemas/Collection'
    LandingPage:
      title: LandingPage
      type: object
      description: OGC API landing page with navigation links.
      properties:
        title:
          type: string
          description: API title.
          example: USGS Water Data OGC APIs
        description:
          type: string
          description: API description.
          example: Access to USGS water data using OGC API standards.
        links:
          type: array
          description: Navigation links.
          items:
            $ref: '#/components/schemas/Link'
    Collection:
      title: Collection
      type: object
      description: Metadata for an OGC API collection.
      properties:
        id:
          type: string
          description: Collection identifier.
          example: monitoring-locations
        title:
          type: string
          description: Human-readable collection title.
          example: Monitoring Locations
        description:
          type: string
          description: Description of the collection.
          example: USGS water monitoring sites.
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    Link:
      title: Link
      type: object
      description: A hypermedia link.
      properties:
        href:
          type: string
          description: Link URL.
          example: https://api.waterdata.usgs.gov/ogcapi/v0/
        rel:
          type: string
          description: Link relation type.
          example: self
        type:
          type: string
          description: Media type of the linked resource.
          example: application/json
        title:
          type: string
          description: Human-readable link title.
          example: This document
  parameters:
    format:
      name: f
      in: query
      required: false
      description: Output format (json, html, jsonld, csv).
      schema:
        type: string
        enum:
        - json
        - html
        - jsonld
        - csv
        default: json
        example: json
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: USGS Water Data API key. Obtain at https://api.waterdata.usgs.gov/signup/
    ApiKeyHeader:
      type: apiKey
      in: header
      name: api_key
      description: USGS Water Data API key passed as a request header.