openapi: 3.1.0
info:
  title: Stormglass Astronomy Tides API
  description: Stormglass provides a global marine and weather API delivering high-resolution forecasts, historical data, and environmental measurements for any coordinate on Earth. The API supports weather point forecasts, marine data, tidal information, solar and astronomical data, biological oceanographic data, and elevation data. Commonly used for maritime navigation, renewable energy forecasting, outdoor activity planning, and environmental monitoring.
  version: v2
  contact:
    name: Stormglass Support
    url: https://stormglass.io/contact
  termsOfService: https://stormglass.io/terms-and-conditions/
servers:
- url: https://api.stormglass.io/v2
  description: Stormglass API v2
security:
- apiKeyAuth: []
tags:
- name: Tides
  description: Tidal data including extremes, sea level, and tide station listings
paths:
  /tide/extremes:
    get:
      operationId: getTideExtremes
      summary: Get Tide Extremes
      description: Retrieve information about high and low tide extremes for a single coordinate. Returns tide high and low events with timestamps and heights. If no datum is specified, values are relative to Mean Sea Level (MSL).
      tags:
      - Tides
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          format: float
        description: Latitude of the desired coordinate
      - name: lng
        in: query
        required: true
        schema:
          type: number
          format: float
        description: Longitude of the desired coordinate
      - name: start
        in: query
        required: false
        schema:
          type: string
        description: Timestamp in UTC for start of time range
      - name: end
        in: query
        required: false
        schema:
          type: string
        description: Timestamp in UTC for end of time range
      - name: datum
        in: query
        required: false
        schema:
          type: string
          enum:
          - MLLW
          - MSL
        description: Datum relative to which values will be reported. Either MLLW or MSL.
      responses:
        '200':
          description: Tide extreme data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TideExtremesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/QuotaExceeded'
  /tide/sea-level:
    get:
      operationId: getTideSeaLevel
      summary: Get Tide Sea Level
      description: Retrieve the sea level in meters on an hourly basis for a single coordinate. If no datum is specified, values are relative to Mean Sea Level (MSL).
      tags:
      - Tides
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          format: float
        description: Latitude of the desired coordinate
      - name: lng
        in: query
        required: true
        schema:
          type: number
          format: float
        description: Longitude of the desired coordinate
      - name: start
        in: query
        required: false
        schema:
          type: string
        description: Timestamp in UTC for start of time range
      - name: end
        in: query
        required: false
        schema:
          type: string
        description: Timestamp in UTC for end of time range
      - name: datum
        in: query
        required: false
        schema:
          type: string
          enum:
          - MLLW
          - MSL
        description: Datum relative to which values will be reported
      responses:
        '200':
          description: Sea level data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TideSeaLevelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/QuotaExceeded'
  /tide/stations:
    get:
      operationId: getTideStations
      summary: List Tide Stations
      description: Retrieve a list of all available tide stations. Returns station names, coordinates, and data sources.
      tags:
      - Tides
      responses:
        '200':
          description: List of tide stations returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TideStationsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tide/stations/area:
    get:
      operationId: getTideStationsArea
      summary: List Tide Stations for Area
      description: Retrieve a list of all tide stations within a defined geographic area defined by a bounding box.
      tags:
      - Tides
      parameters:
      - name: box
        in: query
        required: true
        schema:
          type: string
        description: 'Top-right and bottom-left coordinates of the bounding box in format: lat,lng:lat,lng'
      responses:
        '200':
          description: Tide stations within the area returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TideStationsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    QuotaExceeded:
      description: Daily quota exceeded or payment required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed. Check your API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    TideSeaLevelResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TideSeaLevelHour'
        meta:
          $ref: '#/components/schemas/TideMetaData'
    MetaData:
      type: object
      description: Metadata about the API request including quota information
      properties:
        cost:
          type: integer
          description: Number of API credits consumed by this request
        dailyQuota:
          type: integer
          description: Your daily API call quota
        requestCount:
          type: integer
          description: Total number of API calls made today
        lat:
          type: number
          format: float
          description: Latitude of the requested coordinate
        lng:
          type: number
          format: float
          description: Longitude of the requested coordinate
        params:
          type: array
          items:
            type: string
          description: List of parameters returned
        start:
          type: string
          description: Start timestamp of the returned data
        end:
          type: string
          description: End timestamp of the returned data
    TideExtremePoint:
      type: object
      properties:
        height:
          type: number
          format: float
          description: Tide height in meters
        time:
          type: string
          description: Timestamp in UTC for this tide event
        type:
          type: string
          enum:
          - low
          - high
          description: Type of tide extreme
    TideStation:
      type: object
      properties:
        lat:
          type: number
          format: float
          description: Latitude of the tide station
        lng:
          type: number
          format: float
          description: Longitude of the tide station
        name:
          type: string
          description: Name of the tide station
        source:
          type: string
          description: Tide station owner
    StationMetaData:
      type: object
      properties:
        cost:
          type: integer
        dailyQuota:
          type: integer
        requestCount:
          type: integer
    Error:
      type: object
      properties:
        errors:
          type: object
          additionalProperties:
            type: string
    TideSeaLevelHour:
      type: object
      description: Hourly sea level data from multiple sources
      properties:
        time:
          type: string
          description: Timestamp in UTC
        sg:
          type: number
          format: float
          description: Stormglass composite sea level value in meters
        noaa:
          type: number
          format: float
        icon:
          type: number
          format: float
        dwd:
          type: number
          format: float
    TideExtremesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TideExtremePoint'
          description: List of tide extreme events
        meta:
          $ref: '#/components/schemas/TideMetaData'
    TideStationsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TideStation'
        meta:
          $ref: '#/components/schemas/StationMetaData'
    TideMetaData:
      allOf:
      - $ref: '#/components/schemas/MetaData'
      - type: object
        properties:
          datum:
            type: string
            description: The datum used for tidal measurements
          station:
            type: object
            properties:
              distance:
                type: integer
                description: Distance between tide station and requested coordinate in km
              lat:
                type: number
                format: float
                description: Latitude of the tide station
              lng:
                type: number
                format: float
                description: Longitude of the tide station
              name:
                type: string
                description: Name of the tide station
              source:
                type: string
                description: Tide station owner or data source
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key obtained from your Stormglass account dashboard
externalDocs:
  description: Stormglass API Documentation
  url: https://docs.stormglass.io/