openapi: 3.2.0
info:
  title: DTN Weather Conditions Forecasts API
  description: DTN Weather Conditions API delivers worldwide forecast, current condition, and historical weather data. The API leverages cloud technology and global forecast models to provide validated, continuously calibrated weather data. Supports geospatial queries, time-based filtering, and multi-station requests. Authentication uses OAuth2 Client Credentials; access tokens are obtained from auth.weather.mg/oauth/token and used as Bearer tokens.
  version: 2.0.0
  contact:
    name: DTN Weather API Support
    url: https://devportal.dtn.com/
  license:
    name: DTN Subscription Agreement
    url: https://www.dtn.com/subscription-agreement-standard-terms-conditions/
servers:
- url: https://weather.api.dtn.com/conditions
  description: DTN Weather Conditions API
- url: https://point-forecast.weather.mg
  description: DTN Point Forecast API
- url: https://point-observation.weather.mg
  description: DTN Point Observation API
- url: https://precipitation-forecast.weather.mg
  description: DTN Radar Precipitation Forecast API
security:
- oauth2: []
tags:
- name: Forecasts
  description: Weather forecast data (hourly and daily)
paths:
  /forecast/hourly:
    get:
      operationId: getHourlyForecast
      summary: Get hourly weather forecast
      description: Returns hourly weather forecast data for a specified location. Forecasts available up to 14 days ahead. Supports US and SI unit systems.
      tags:
      - Forecasts
      servers:
      - url: https://point-forecast.weather.mg
      parameters:
      - name: locatedAt
        in: query
        required: true
        description: Latitude,longitude or station ID
        schema:
          type: string
      - name: validPeriod
        in: query
        description: 'Date/time range for the forecast. Format: startISO8601/endISO8601 (e.g., 2026-03-18T00:00:00Z/2026-03-25T00:00:00Z)'
        schema:
          type: string
      - name: fields
        in: query
        description: Comma-separated forecast fields to return
        schema:
          type: string
          example: airTemperatureInCelsius,precipitationAmountInMillimeter,windSpeedInMeterPerSecond,windDirectionInDegree
      - name: units
        in: query
        schema:
          type: string
          enum:
          - US
          - SI
          default: SI
      - name: meteoGroupStationId
        in: query
        description: Include station ID in response when using station-based query
        schema:
          type: boolean
      responses:
        '200':
          description: Hourly weather forecast
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HourlyForecastResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /forecast/daily:
    get:
      operationId: getDailyForecast
      summary: Get daily weather forecast
      description: Returns daily weather forecast data for a specified location, including high/low temperatures, precipitation probability, and weather symbols.
      tags:
      - Forecasts
      servers:
      - url: https://point-forecast.weather.mg
      parameters:
      - name: locatedAt
        in: query
        required: true
        schema:
          type: string
      - name: validPeriod
        in: query
        schema:
          type: string
      - name: fields
        in: query
        schema:
          type: string
          example: maxAirTemperatureInCelsius,minAirTemperatureInCelsius,precipitationProbabilityInPercent,weatherSymbol
      - name: units
        in: query
        schema:
          type: string
          enum:
          - US
          - SI
          default: SI
      responses:
        '200':
          description: Daily weather forecast
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyForecastResponse'
components:
  schemas:
    HourlyForecastPoint:
      type: object
      properties:
        validAt:
          type: string
          format: date-time
        airTemperatureInCelsius:
          type: number
        precipitationAmountInMillimeter:
          type: number
        precipitationProbabilityInPercent:
          type: number
        windSpeedInMeterPerSecond:
          type: number
        windDirectionInDegree:
          type: number
        windGustInMeterPerSecond:
          type: number
        relativeHumidityInPercent:
          type: number
        weatherSymbol:
          type: integer
    HourlyForecastResponse:
      type: object
      properties:
        generatedAt:
          type: string
          format: date-time
        units:
          type: string
        location:
          $ref: '#/components/schemas/Location'
        forecasts:
          type: array
          items:
            $ref: '#/components/schemas/HourlyForecastPoint'
    DailyForecastResponse:
      type: object
      properties:
        generatedAt:
          type: string
          format: date-time
        location:
          $ref: '#/components/schemas/Location'
        forecasts:
          type: array
          items:
            $ref: '#/components/schemas/DailyForecastPoint'
    DailyForecastPoint:
      type: object
      properties:
        validOn:
          type: string
          format: date
        maxAirTemperatureInCelsius:
          type: number
        minAirTemperatureInCelsius:
          type: number
        precipitationAmountInMillimeter:
          type: number
        precipitationProbabilityInPercent:
          type: number
        weatherSymbol:
          type: integer
        windSpeedInMeterPerSecond:
          type: number
        windDirectionInDegree:
          type: number
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    Location:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        elevation:
          type: number
          description: Elevation in meters
  responses:
    Unauthorized:
      description: Missing or invalid Bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid query parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 Client Credentials for DTN Weather APIs
      flows:
        clientCredentials:
          tokenUrl: https://auth.weather.mg/oauth/token
          scopes:
            weather:read: Access weather data