openapi: 3.0.3
info:
  title: USGS Earthquake Notifications, Feeds, and Web Services Catalog Time Series Data API
  description: The USGS Earthquake Hazards Program provides real-time earthquake data through the FDSN (International Federation of Digital Seismograph Networks) Event Web Service. This API allows searching the USGS ANSS (Advanced National Seismic System) ComCat earthquake catalog for event data using geographic, temporal, magnitude, and other filters. Responses are available in GeoJSON, CSV, KML, QuakeML, and text formats.
  version: '1.0'
  contact:
    name: USGS Earthquake Hazards Program
    url: https://earthquake.usgs.gov/
    email: shake-admin@usgs.gov
  license:
    name: Public Domain (U.S. Government Work)
    url: https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits
  x-generated-from: documentation
servers:
- url: https://earthquake.usgs.gov/fdsnws/event/1
  description: USGS FDSN Event Web Service
tags:
- name: Time Series Data
  description: Continuous and daily value water data from USGS monitoring locations.
paths:
  /collections/time-series/items:
    get:
      operationId: getTimeSeries
      summary: USGS Water Data Get Time Series
      description: Retrieve USGS water data time series records including continuous sensor measurements (streamflow, stage, temperature, specific conductance, etc.) and daily values. Filter by monitoring location, parameter code, time range, and spatial extent.
      tags:
      - Time Series Data
      parameters:
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/time'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/format'
      - name: monitoringLocationIdentifier
        in: query
        required: false
        description: Filter by specific monitoring location identifier (e.g., USGS-11169025).
        schema:
          type: string
          example: USGS-11169025
      - name: observedPropertyId
        in: query
        required: false
        description: USGS parameter code for the measured property (e.g., 00060 for streamflow in cfs, 00065 for gage height in feet).
        schema:
          type: string
          example: '00060'
      - name: statistic
        in: query
        required: false
        description: Statistic code for daily values (00001=max, 00002=min, 00003=mean).
        schema:
          type: string
          example: '00003'
      responses:
        '200':
          description: Collection of time series records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesCollection'
              examples:
                GetTimeSeries200Example:
                  summary: Default getTimeSeries 200 response
                  x-microcks-default: true
                  value:
                    type: FeatureCollection
                    features:
                    - type: Feature
                      properties:
                        monitoringLocationIdentifier: USGS-11169025
                        observedPropertyId: '00060'
                        observedPropertyName: Streamflow, ft³/s
                        phenomenonTime: '2025-03-15T14:00:00Z'
                        result: 450.0
                        resultUnitCode: ft3/s
                        resultQualityCode: P
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API key missing or unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    TimeSeriesProperties:
      title: TimeSeriesProperties
      type: object
      description: Properties of a single water data observation.
      properties:
        monitoringLocationIdentifier:
          type: string
          description: Monitoring location identifier.
          example: USGS-11169025
        observedPropertyId:
          type: string
          description: USGS parameter code for the measured property.
          example: '00060'
        observedPropertyName:
          type: string
          description: Human-readable parameter name.
          example: Streamflow, ft³/s
        phenomenonTime:
          type: string
          format: date-time
          description: ISO 8601 datetime when the measurement was taken.
          example: '2025-03-15T14:00:00Z'
        result:
          type: number
          description: Measured value.
          example: 450.0
        resultUnitCode:
          type: string
          description: Unit of measurement.
          example: ft3/s
        resultQualityCode:
          type: string
          description: 'Quality code: P (provisional), A (approved), e (estimated).'
          example: P
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Standard OGC API error response.
      properties:
        code:
          type: string
          description: Error code.
          example: InvalidParameter
        description:
          type: string
          description: Human-readable error description.
          example: Invalid value for parameter bbox.
    TimeSeriesCollection:
      title: TimeSeriesCollection
      type: object
      description: Collection of USGS water data time series observations.
      properties:
        type:
          type: string
          description: GeoJSON type.
          example: FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/TimeSeriesFeature'
        numberMatched:
          type: integer
          description: Total number of matching observations.
          example: 8760
        numberReturned:
          type: integer
          description: Number of observations returned.
          example: 100
    TimeSeriesFeature:
      title: TimeSeriesFeature
      type: object
      description: A single time series observation from a USGS monitoring location.
      properties:
        type:
          type: string
          description: GeoJSON type.
          example: Feature
        properties:
          $ref: '#/components/schemas/TimeSeriesProperties'
  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
    time:
      name: time
      in: query
      required: false
      description: Temporal filter in RFC 3339 or ISO 8601 format. Use a single datetime or interval (e.g., 2025-01-01/2025-03-01).
      schema:
        type: string
        example: 2025-01-01/2025-03-01
    bbox:
      name: bbox
      in: query
      required: false
      description: Bounding box spatial filter as [min_lon,min_lat,max_lon,max_lat]. Optionally include min_elev and max_elev for 6-coordinate form.
      schema:
        type: string
        example: -125,25,-65,50
    offset:
      name: offset
      in: query
      required: false
      description: Starting offset for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
        example: 0
    limit:
      name: limit
      in: query
      required: false
      description: Number of results to return (default 100, max 10000).
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 100
        example: 100