openapi: 3.1.0
info:
  title: USGS Water Services API
  description: >-
    The U.S. Geological Survey Water Services API provides real-time and
    historical surface-water, groundwater, and water-quality data for sites
    across the United States. Endpoints follow the WaterML / IV (instantaneous
    values), DV (daily values), and Site Service patterns.
  version: '1'
  contact:
    name: USGS Water Mission Area
    url: https://water.usgs.gov/
  license:
    name: Public Domain
    url: https://creativecommons.org/publicdomain/mark/1.0/
externalDocs:
  description: USGS Water Services
  url: https://waterservices.usgs.gov/
servers:
  - url: https://waterservices.usgs.gov/nwis
    description: National Water Information System
tags:
  - name: Sites
    description: Water-monitoring sites
  - name: InstantaneousValues
    description: Real-time instantaneous values
  - name: DailyValues
    description: Daily statistical values
paths:
  /site/:
    get:
      tags: [Sites]
      summary: Look up monitoring sites
      operationId: getSites
      parameters:
        - $ref: '#/components/parameters/format'
        - name: stateCd
          in: query
          schema:
            type: string
            pattern: ^[a-z]{2}$
        - name: huc
          in: query
          schema:
            type: string
        - name: bBox
          in: query
          schema:
            type: string
        - name: countyCd
          in: query
          schema:
            type: string
        - name: siteType
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Site response
  /iv/:
    get:
      tags: [InstantaneousValues]
      summary: Real-time instantaneous values
      operationId: getInstantaneousValues
      parameters:
        - $ref: '#/components/parameters/format'
        - name: sites
          in: query
          required: true
          schema:
            type: string
        - name: parameterCd
          in: query
          schema:
            type: string
        - name: period
          in: query
          schema:
            type: string
            example: P7D
      responses:
        '200':
          description: Instantaneous values response
  /dv/:
    get:
      tags: [DailyValues]
      summary: Daily statistical values
      operationId: getDailyValues
      parameters:
        - $ref: '#/components/parameters/format'
        - name: sites
          in: query
          required: true
          schema:
            type: string
        - name: parameterCd
          in: query
          schema:
            type: string
        - name: startDT
          in: query
          schema:
            type: string
            format: date
        - name: endDT
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Daily values response
components:
  parameters:
    format:
      name: format
      in: query
      schema:
        type: string
        enum: [json, rdb, waterml, xml]
        default: json