openapi: 3.0.3
info:
  title: USACE CWMS Data Catalog Timeseries API
  description: The Corps Water Management System (CWMS) Data API (CDA) is a RESTful API that enables secure data exchange for publicly available USACE water management data. The API provides access to timeseries data, location information, ratings, reservoirs, levels, and other water resource data maintained by the US Army Corps of Engineers.
  version: 2.0.0
  contact:
    name: USACE HEC
    url: https://cwms-data.usace.army.mil/cwms-data/
  license:
    name: Public Domain
    url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://cwms-data.usace.army.mil/cwms-data
  description: Production server (public data)
- url: https://cwms-data-test.cwbi.us/cwms-data
  description: Test server
tags:
- name: Timeseries
paths:
  /timeseries:
    get:
      operationId: getTimeseries
      summary: Get Timeseries Data
      description: Retrieves timeseries data from the CWMS database. Results can be filtered by office, location, and time range. Dates may be in ISO 8601 format or milliseconds since the Unix epoch.
      tags:
      - Timeseries
      parameters:
      - name: name
        in: query
        required: true
        description: Timeseries identifier (e.g., TULA.Flow.Inst.1Hour.0.CBT-RAW)
        schema:
          type: string
      - name: office
        in: query
        required: false
        description: The office that owns the timeseries
        schema:
          type: string
      - name: unit
        in: query
        required: false
        description: The units for the time series values
        schema:
          type: string
      - name: datum
        in: query
        required: false
        description: The vertical datum for elevation timeseries
        schema:
          type: string
          enum:
          - NGVD29
          - NAVD88
      - name: begin
        in: query
        required: false
        description: Start time in ISO 8601 format or milliseconds
        schema:
          type: string
      - name: end
        in: query
        required: false
        description: End time in ISO 8601 format or milliseconds
        schema:
          type: string
      - name: timezone
        in: query
        required: false
        description: Timezone for time formatting
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: Response format
        schema:
          type: string
          enum:
          - json
          - xml
          - tab
          - csv
      - name: page-size
        in: query
        required: false
        description: Number of records to return per page
        schema:
          type: integer
          default: 500
      - name: page
        in: query
        required: false
        description: Page cursor for pagination
        schema:
          type: string
      responses:
        '200':
          description: Successful response with timeseries data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeseriesResponse'
        '404':
          description: Timeseries not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /timeseries/catalog:
    get:
      operationId: getTimeseriesCatalog
      summary: Get Timeseries Catalog
      description: Returns a catalog of available timeseries identifiers, optionally filtered by office and location.
      tags:
      - Timeseries
      parameters:
      - name: office
        in: query
        required: false
        description: Filter by office identifier
        schema:
          type: string
      - name: timeseries-id-like
        in: query
        required: false
        description: Filter by timeseries ID pattern (supports SQL LIKE syntax)
        schema:
          type: string
      - name: page-size
        in: query
        required: false
        description: Number of catalog entries per page
        schema:
          type: integer
          default: 500
      - name: page
        in: query
        required: false
        description: Pagination cursor
        schema:
          type: string
      responses:
        '200':
          description: Catalog of timeseries identifiers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
components:
  schemas:
    TimeseriesResponse:
      type: object
      description: Paginated response containing timeseries data values
      properties:
        name:
          type: string
          description: Timeseries identifier
        office-id:
          type: string
          description: Office that owns the timeseries
        units:
          type: string
          description: Unit of measure for values
        begin:
          type: string
          description: Start time of returned data
        end:
          type: string
          description: End time of returned data
        values:
          type: array
          description: Array of [timestamp, value, quality-code] tuples
          items:
            type: array
            items:
              oneOf:
              - type: number
              - type: integer
        page:
          type: string
          description: Current page cursor
        next-page:
          type: string
          description: Next page cursor for pagination
    CatalogResponse:
      type: object
      description: Paginated catalog of available data items
      properties:
        page:
          type: string
          description: Current page cursor
        next-page:
          type: string
          description: Next page cursor
        total:
          type: integer
          description: Total number of entries
        page-size:
          type: integer
          description: Records per page
        entries:
          type: array
          items:
            type: object
            properties:
              office:
                type: string
              name:
                type: string
              units-available:
                type: array
                items:
                  type: string
    Error:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Error message