National Oceanic and Atmospheric Administration Observations API

openapi: 3.2.0
info:
  title: NOAA CO-OPS Data Observations API
  description: The NOAA Center for Operational Oceanographic Products and Services (CO-OPS) Data API provides observations and predictions from CO-OPS stations including water levels, tides, currents, meteorological data, and derived products. Operated by the National Oceanic and Atmospheric Administration (NOAA), U.S. Department of Commerce.
  version: '1.0'
  contact:
    name: CO-OPS User Services
    email: co-ops.userservices@noaa.gov
    url: https://tidesandcurrents.noaa.gov/
  license:
    name: U.S. Government Work
    url: https://www.usa.gov/government-works
servers:
- url: https://api.tidesandcurrents.noaa.gov/api/prod
  description: NOAA CO-OPS production data API
tags:
- name: Observations
  description: Retrieve observations and predictions from CO-OPS stations.
paths:
  /datagetter:
    get:
      tags:
      - Observations
      summary: Retrieve CO-OPS station observations and predictions
      description: Returns observations or predictions for a single CO-OPS station. Use date or begin_date/end_date/range to control the time window, and product to choose the dataset (water_level, predictions, currents, air_temperature, wind, etc.).
      operationId: getData
      parameters:
      - name: station
        in: query
        required: true
        description: 7-character CO-OPS station ID, or currents identifier.
        schema:
          type: string
      - name: product
        in: query
        required: true
        description: Data product to retrieve.
        schema:
          type: string
          enum:
          - water_level
          - hourly_height
          - high_low
          - daily_mean
          - monthly_mean
          - one_minute_water_level
          - predictions
          - air_gap
          - air_temperature
          - water_temperature
          - wind
          - air_pressure
          - visibility
          - humidity
          - salinity
          - conductivity
          - currents
          - currents_predictions
          - currents_header
          - ofs_water_level
          - datums
      - name: begin_date
        in: query
        description: Start of the time window (yyyyMMdd, yyyyMMdd HH:mm, MM/dd/yyyy, or MM/dd/yyyy HH:mm).
        schema:
          type: string
      - name: end_date
        in: query
        description: End of the time window.
        schema:
          type: string
      - name: range
        in: query
        description: Hours of data to retrieve relative to begin_date, end_date, or now.
        schema:
          type: integer
      - name: date
        in: query
        description: Convenience selector (today, latest, recent).
        schema:
          type: string
          enum:
          - today
          - latest
          - recent
      - name: datum
        in: query
        description: Vertical datum reference for water level products.
        schema:
          type: string
          enum:
          - MLLW
          - MHHW
          - MSL
          - MTL
          - NAVD
          - STND
          - CRD
          - IGLD
          - LWD
      - name: units
        in: query
        description: Unit system for returned values.
        schema:
          type: string
          enum:
          - metric
          - english
      - name: time_zone
        in: query
        description: Time zone for timestamps.
        schema:
          type: string
          enum:
          - gmt
          - lst
          - lst_ldt
      - name: format
        in: query
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - xml
          - csv
      - name: interval
        in: query
        description: Sampling interval for predictions and meteorological data.
        schema:
          type: string
      - name: bin
        in: query
        description: Bin number for currents requests.
        schema:
          type: integer
      - name: vel_type
        in: query
        description: Velocity reporting style for currents (speed_dir or default).
        schema:
          type: string
          enum:
          - speed_dir
          - default
      - name: application
        in: query
        description: Application identifier for the requesting client (recommended).
        schema:
          type: string
      responses:
        '200':
          description: Observations or predictions in the requested format.
        '400':
          description: Invalid request parameters.