openapi: 3.0.3
info:
  title: USACE Corps Water Management System Data API
  description: >-
    The Corps Water Management System Data API (CDA) is a REST service
    providing programmatic access to USACE water management data. It supports
    retrieval of time series measurements, monitoring locations, rating curves,
    reservoir pool levels, lock data, and operational information across Army
    Corps of Engineers projects. Public data is accessible without
    authentication; write operations require an API key.
  version: latest
  contact:
    url: https://cwms-data.usace.army.mil/cwms-data/
  license:
    name: US Government Work
    url: https://www.usa.gov/government-works
servers:
  - url: https://cwms-data.usace.army.mil/cwms-data/api/latest
    description: National CWMS Data API Production Server
  - url: https://water.usace.army.mil/cwms-data/api/latest
    description: USACE Water Data Production Server
tags:
  - name: Time Series
    description: Time series data retrieval and management
  - name: Locations
    description: CWMS monitoring locations and metadata
  - name: Ratings
    description: Rating curves and tables
  - name: Levels
    description: Location levels and pool data
  - name: Catalog
    description: Data catalog and discovery
  - name: Offices
    description: USACE district offices
  - name: Projects
    description: USACE projects and reservoirs
  - name: Locks
    description: Lock and waterway navigation data
  - name: Measurements
    description: Field measurements and observations
paths:
  /timeseries:
    get:
      operationId: getTimeSeries
      summary: Get Time Series Data
      description: >-
        Returns time series data for a specified location and parameter.
        Supports retrieval of streamflow, gage height, reservoir levels,
        temperature, and other continuous measurements. Results are paginated
        for large datasets.
      tags:
        - Time Series
      parameters:
        - name: office
          in: query
          description: USACE district office ID (e.g., CWMS, SWT, LRH)
          required: false
          schema:
            type: string
        - name: name
          in: query
          description: >-
            Time series ID in format Location.Parameter.Type.Interval.Duration.Version
          required: false
          schema:
            type: string
        - name: begin
          in: query
          description: Start of the time window (ISO 8601 or milliseconds since epoch)
          required: false
          schema:
            type: string
        - name: end
          in: query
          description: End of the time window (ISO 8601 or milliseconds since epoch)
          required: false
          schema:
            type: string
        - name: datum
          in: query
          description: Elevation datum for stage data (e.g., NAVD88, NGVD29)
          required: false
          schema:
            type: string
        - name: unit
          in: query
          description: Unit of measure for the output (e.g., EN for English, SI for metric)
          required: false
          schema:
            type: string
        - name: timezone
          in: query
          description: Timezone for date/time values in response
          required: false
          schema:
            type: string
            default: UTC
        - name: format
          in: query
          description: Response format
          required: false
          schema:
            type: string
            enum:
              - json
              - tab
              - csv
              - xml
            default: json
        - name: page-size
          in: query
          description: Number of values per page
          required: false
          schema:
            type: integer
            default: 500
        - name: page
          in: query
          description: Page cursor for pagination (from previous response)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Time series data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesResponse'
        '400':
          description: Bad request - invalid parameters
        '404':
          description: Time series not found
  /timeseries/catalog:
    get:
      operationId: getTimeSeriesCatalog
      summary: Get Time Series Catalog
      description: Returns a catalog of available time series identifiers.
      tags:
        - Catalog
        - Time Series
      parameters:
        - name: office
          in: query
          description: Filter by USACE district office ID
          required: false
          schema:
            type: string
        - name: timeseries-id-regex
          in: query
          description: Regular expression pattern to filter time series IDs
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          description: Pagination cursor from previous response
          required: false
          schema:
            type: string
        - name: page-size
          in: query
          description: Number of entries per page
          required: false
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Time series catalog entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesCatalogResponse'
  /locations:
    get:
      operationId: getLocations
      summary: Get Locations
      description: >-
        Returns a list of CWMS monitoring locations matching the specified
        criteria. Locations represent physical sites where measurements
        are taken or water management occurs.
      tags:
        - Locations
      parameters:
        - name: office
          in: query
          description: Filter by USACE district office ID
          required: false
          schema:
            type: string
        - name: names
          in: query
          description: Pipe-separated list of location IDs to retrieve
          required: false
          schema:
            type: string
        - name: unit
          in: query
          description: Unit system for coordinates (EN or SI)
          required: false
          schema:
            type: string
        - name: datum
          in: query
          description: Elevation datum for location elevations
          required: false
          schema:
            type: string
        - name: format
          in: query
          description: Response format
          required: false
          schema:
            type: string
            enum:
              - json
              - tab
              - csv
              - xml
            default: json
      responses:
        '200':
          description: Location data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationsResponse'
        '404':
          description: Location not found
  /locations/{locationId}:
    get:
      operationId: getLocation
      summary: Get Location Details
      description: Returns details for a single CWMS monitoring location.
      tags:
        - Locations
      parameters:
        - name: locationId
          in: path
          description: CWMS location identifier
          required: true
          schema:
            type: string
        - name: office
          in: query
          description: USACE district office ID
          required: true
          schema:
            type: string
        - name: unit
          in: query
          description: Unit system for coordinates
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Location details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '404':
          description: Location not found
  /locations/catalog:
    get:
      operationId: getLocationCatalog
      summary: Get Location Catalog
      description: Returns a searchable catalog of all available CWMS locations.
      tags:
        - Catalog
        - Locations
      parameters:
        - name: office
          in: query
          description: Filter by USACE district office ID
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          description: Pagination cursor
          required: false
          schema:
            type: string
        - name: page-size
          in: query
          description: Number of entries per page
          required: false
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Location catalog entries
          content:
            application/json:
              schema:
                type: object
  /ratings:
    get:
      operationId: getRatings
      summary: Get Rating Curves
      description: >-
        Returns rating curves used to convert gage height (stage) measurements
        to discharge (streamflow) values. Rating curves are essential for
        computing streamflow from continuous stage measurements.
      tags:
        - Ratings
      parameters:
        - name: office
          in: query
          description: USACE district office ID
          required: false
          schema:
            type: string
        - name: rating-id-mask
          in: query
          description: Pattern mask to filter rating IDs
          required: false
          schema:
            type: string
        - name: start
          in: query
          description: Start of the time window for effective ratings
          required: false
          schema:
            type: string
        - name: end
          in: query
          description: End of the time window for effective ratings
          required: false
          schema:
            type: string
        - name: method
          in: query
          description: Rating method (e.g., LINEAR, LOGARITHMIC)
          required: false
          schema:
            type: string
        - name: format
          in: query
          description: Response format
          required: false
          schema:
            type: string
            enum:
              - json
              - xml
            default: json
      responses:
        '200':
          description: Rating curves
          content:
            application/json:
              schema:
                type: object
  /levels:
    get:
      operationId: getLevels
      summary: Get Location Levels
      description: >-
        Returns location level data including pool elevations, flood stages,
        and operational thresholds for CWMS monitoring locations.
      tags:
        - Levels
      parameters:
        - name: office
          in: query
          description: USACE district office ID
          required: false
          schema:
            type: string
        - name: location-id
          in: query
          description: CWMS location identifier
          required: false
          schema:
            type: string
        - name: parameter-id
          in: query
          description: Parameter identifier (e.g., Stage, Elev)
          required: false
          schema:
            type: string
        - name: unit
          in: query
          description: Unit system for output values
          required: false
          schema:
            type: string
        - name: begin
          in: query
          description: Start of time window
          required: false
          schema:
            type: string
        - name: end
          in: query
          description: End of time window
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Location level data
          content:
            application/json:
              schema:
                type: object
  /offices:
    get:
      operationId: getOffices
      summary: Get USACE Offices
      description: >-
        Returns a list of USACE district offices with their identifiers and
        information. Offices are used to scope data queries within the
        CWMS system.
      tags:
        - Offices
      responses:
        '200':
          description: List of USACE district offices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfficesResponse'
  /projects:
    get:
      operationId: getProjects
      summary: Get USACE Projects
      description: >-
        Returns USACE projects such as reservoirs, navigation projects,
        and flood control structures with their operational parameters.
      tags:
        - Projects
      parameters:
        - name: office
          in: query
          description: Filter by USACE district office ID
          required: false
          schema:
            type: string
        - name: project-id-mask
          in: query
          description: Pattern mask to filter project IDs
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of USACE projects
          content:
            application/json:
              schema:
                type: object
  /measurements:
    get:
      operationId: getMeasurements
      summary: Get Field Measurements
      description: >-
        Returns field measurement data collected at CWMS locations including
        streamflow discharge measurements used for rating curve development.
      tags:
        - Measurements
      parameters:
        - name: office
          in: query
          description: USACE district office ID
          required: false
          schema:
            type: string
        - name: location-id
          in: query
          description: CWMS location identifier
          required: false
          schema:
            type: string
        - name: unit-system
          in: query
          description: Unit system for output values (EN or SI)
          required: false
          schema:
            type: string
        - name: begin
          in: query
          description: Start of time window
          required: false
          schema:
            type: string
        - name: end
          in: query
          description: End of time window
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Field measurements
          content:
            application/json:
              schema:
                type: object
  /basins:
    get:
      operationId: getBasins
      summary: Get Basins
      description: Returns hydrologic basins defined in CWMS.
      tags:
        - Locations
      parameters:
        - name: office
          in: query
          description: USACE district office ID
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of basins
          content:
            application/json:
              schema:
                type: object
  /pools:
    get:
      operationId: getPools
      summary: Get Reservoir Pools
      description: >-
        Returns reservoir pool definitions including storage zones, flood
        control pools, and conservation pools for USACE projects.
      tags:
        - Levels
        - Projects
      parameters:
        - name: office
          in: query
          description: USACE district office ID
          required: false
          schema:
            type: string
        - name: project-id-mask
          in: query
          description: Pattern mask to filter project IDs
          required: false
          schema:
            type: string
        - name: name-mask
          in: query
          description: Pattern mask to filter pool names
          required: false
          schema:
            type: string
        - name: unit
          in: query
          description: Unit system for output values
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Reservoir pool definitions
          content:
            application/json:
              schema:
                type: object
  /parameters:
    get:
      operationId: getParameters
      summary: Get Parameters
      description: >-
        Returns the list of CWMS parameters available for time series and
        location level queries (e.g., Stage, Flow, Elev, Temp-Water).
      tags:
        - Catalog
      responses:
        '200':
          description: List of available CWMS parameters
          content:
            application/json:
              schema:
                type: object
  /units:
    get:
      operationId: getUnits
      summary: Get Units
      description: Returns the list of measurement units available in the CWMS system.
      tags:
        - Catalog
      responses:
        '200':
          description: List of available units
          content:
            application/json:
              schema:
                type: object
  /states:
    get:
      operationId: getStates
      summary: Get States
      description: Returns the list of US states recognized in the CWMS system.
      tags:
        - Catalog
      responses:
        '200':
          description: List of states
          content:
            application/json:
              schema:
                type: object
  /counties:
    get:
      operationId: getCounties
      summary: Get Counties
      description: Returns the list of US counties with CWMS location data.
      tags:
        - Catalog
      responses:
        '200':
          description: List of counties
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    TimeSeriesResponse:
      type: object
      properties:
        name:
          type: string
          description: Time series ID
        office-id:
          type: string
          description: USACE district office ID
        units:
          type: string
          description: Unit of measure for values
        interval:
          type: integer
          description: Interval between values in minutes
        interval-offset:
          type: integer
          description: Offset in minutes from midnight
        time-zone:
          type: string
          description: Time zone for date/time values
        values:
          type: array
          items:
            type: array
            description: '[timestamp_ms, value, quality_code]'
            items:
              type: number
        page:
          type: string
          description: Cursor for retrieving the next page
        next-page:
          type: string
          description: Next page cursor
        total:
          type: integer
          description: Total number of values matching the query
    TimeSeriesCatalogResponse:
      type: object
      properties:
        page:
          type: string
        next-page:
          type: string
        total:
          type: integer
        entries:
          type: array
          items:
            type: object
            properties:
              office:
                type: string
              name:
                type: string
              units:
                type: string
              interval:
                type: string
              interval-offset:
                type: integer
    LocationsResponse:
      type: object
      properties:
        locations:
          type: object
          properties:
            properties:
              type: object
              properties:
                office-id:
                  type: string
                name:
                  type: string
                latitude:
                  type: number
                longitude:
                  type: number
                elevation:
                  type: number
                horizontal-datum:
                  type: string
                vertical-datum:
                  type: string
                time-zone-name:
                  type: string
                location-type:
                  type: string
                county-name:
                  type: string
                state-initial:
                  type: string
                active:
                  type: boolean
                public-name:
                  type: string
                long-name:
                  type: string
                description:
                  type: string
    Location:
      type: object
      properties:
        office-id:
          type: string
          description: USACE district office ID
        name:
          type: string
          description: Location identifier
        latitude:
          type: number
          description: Latitude in decimal degrees
        longitude:
          type: number
          description: Longitude in decimal degrees
        elevation:
          type: number
          description: Elevation above datum
        horizontal-datum:
          type: string
          description: Horizontal coordinate datum
        vertical-datum:
          type: string
          description: Vertical elevation datum
        time-zone-name:
          type: string
          description: Time zone for the location
        location-type:
          type: string
          description: Classification of the location type
        county-name:
          type: string
          description: County name
        state-initial:
          type: string
          description: Two-letter state abbreviation
        active:
          type: boolean
          description: Whether the location is currently active
        public-name:
          type: string
          description: Public-facing display name
        long-name:
          type: string
          description: Full long name of the location
        description:
          type: string
          description: Description of the location
    OfficesResponse:
      type: object
      properties:
        offices:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Office identifier/abbreviation
              long-name:
                type: string
                description: Full office name
              headquarters:
                type: boolean
                description: Whether this is a headquarters office