openapi: 3.1.0
info:
  title: OpenWeather and Air Pollution One Call API
  version: 1.0.0
  description: Programmatic access to the OpenWeather One Call API for current, minute, hourly, and daily forecasts plus government weather alerts, and the OpenWeather Air Pollution API for current, forecast, and historical air quality data including the Air Quality Index and pollutant concentrations.
  contact:
    name: OpenWeather
    url: https://openweathermap.org/api
  license:
    name: Creative Commons Attribution-ShareAlike 4.0 International
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://api.openweathermap.org/data/3.0
  description: One Call API base URL
- url: https://api.openweathermap.org/data/2.5
  description: Air Pollution API base URL
security:
- appid: []
tags:
- name: One Call
  description: Combined current weather, forecast, and historical weather data.
paths:
  /onecall:
    get:
      operationId: getOneCall
      summary: Current and forecast weather data for a coordinate
      description: Returns current weather, minute-by-minute forecast for one hour, hourly forecast for 48 hours, daily forecast for 8 days, and any government weather alerts for the supplied latitude and longitude.
      tags:
      - One Call
      parameters:
      - name: lat
        in: query
        required: true
        description: Latitude in decimal degrees, range -90 to 90.
        schema:
          type: number
          format: float
      - name: lon
        in: query
        required: true
        description: Longitude in decimal degrees, range -180 to 180.
        schema:
          type: number
          format: float
      - name: exclude
        in: query
        required: false
        description: Comma-separated list of forecast blocks to omit from the response. Allowed values are current, minutely, hourly, daily, and alerts.
        schema:
          type: string
      - name: units
        in: query
        required: false
        description: Units of measurement. One of standard, metric, or imperial. Default is standard (Kelvin, m/s).
        schema:
          type: string
          enum:
          - standard
          - metric
          - imperial
      - name: lang
        in: query
        required: false
        description: ISO language code for localized response text.
        schema:
          type: string
      - name: appid
        in: query
        required: true
        description: OpenWeather API key.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with combined weather data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OneCallResponse'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized. Missing or invalid API key.
        '429':
          description: Too many requests. Rate or quota limit exceeded.
  /onecall/timemachine:
    get:
      operationId: getOneCallTimemachine
      summary: Historical weather data for a coordinate and timestamp
      description: Returns historical weather data for the supplied latitude, longitude, and Unix UTC timestamp. Data depth depends on the subscription plan.
      tags:
      - One Call
      parameters:
      - name: lat
        in: query
        required: true
        description: Latitude in decimal degrees.
        schema:
          type: number
          format: float
      - name: lon
        in: query
        required: true
        description: Longitude in decimal degrees.
        schema:
          type: number
          format: float
      - name: dt
        in: query
        required: true
        description: Unix UTC timestamp for the requested historical reading.
        schema:
          type: integer
          format: int64
      - name: units
        in: query
        required: false
        schema:
          type: string
          enum:
          - standard
          - metric
          - imperial
      - name: lang
        in: query
        required: false
        schema:
          type: string
      - name: appid
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Historical weather data response.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
components:
  schemas:
    OneCallResponse:
      type: object
      properties:
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        timezone:
          type: string
        timezone_offset:
          type: integer
        current:
          type: object
        minutely:
          type: array
          items:
            type: object
        hourly:
          type: array
          items:
            type: object
        daily:
          type: array
          items:
            type: object
        alerts:
          type: array
          items:
            type: object
  securitySchemes:
    appid:
      type: apiKey
      in: query
      name: appid