openapi: 3.1.0
info:
  title: OpenWeather One Call and Air Pollution 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: Air Pollution
  description: Current, forecast, and historical air pollution data.
paths:
  /air_pollution:
    get:
      operationId: getCurrentAirPollution
      summary: Current air pollution data for a coordinate
      description: Returns current air pollution data including the Air Quality Index and concentrations of CO, NO, NO2, O3, SO2, PM2.5, PM10, and NH3 for the supplied latitude and longitude.
      tags:
      - Air Pollution
      servers:
      - url: https://api.openweathermap.org/data/2.5
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          format: float
      - name: lon
        in: query
        required: true
        schema:
          type: number
          format: float
      - name: appid
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Air pollution response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirPollutionResponse'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /air_pollution/forecast:
    get:
      operationId: getAirPollutionForecast
      summary: Hourly air pollution forecast for a coordinate
      description: Returns the hourly air pollution forecast for the next 5 days for the supplied latitude and longitude.
      tags:
      - Air Pollution
      servers:
      - url: https://api.openweathermap.org/data/2.5
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          format: float
      - name: lon
        in: query
        required: true
        schema:
          type: number
          format: float
      - name: appid
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Air pollution forecast response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirPollutionResponse'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /air_pollution/history:
    get:
      operationId: getAirPollutionHistory
      summary: Historical air pollution data for a coordinate
      description: Returns historical hourly air pollution data for the supplied latitude, longitude, and Unix UTC start/end timestamps. Data is available from 27 November 2020 onwards.
      tags:
      - Air Pollution
      servers:
      - url: https://api.openweathermap.org/data/2.5
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          format: float
      - name: lon
        in: query
        required: true
        schema:
          type: number
          format: float
      - name: start
        in: query
        required: true
        description: Unix UTC start timestamp.
        schema:
          type: integer
          format: int64
      - name: end
        in: query
        required: true
        description: Unix UTC end timestamp.
        schema:
          type: integer
          format: int64
      - name: appid
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Historical air pollution response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirPollutionResponse'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
components:
  schemas:
    AirPollutionResponse:
      type: object
      properties:
        coord:
          type: object
          properties:
            lat:
              type: number
              format: float
            lon:
              type: number
              format: float
        list:
          type: array
          items:
            $ref: '#/components/schemas/AirPollutionListItem'
    AirPollutionComponents:
      type: object
      properties:
        co:
          type: number
          format: float
        false:
          type: number
          format: float
        no2:
          type: number
          format: float
        o3:
          type: number
          format: float
        so2:
          type: number
          format: float
        pm2_5:
          type: number
          format: float
        pm10:
          type: number
          format: float
        nh3:
          type: number
          format: float
    AirPollutionListItem:
      type: object
      properties:
        dt:
          type: integer
          format: int64
        main:
          type: object
          properties:
            aqi:
              type: integer
              description: Air Quality Index. 1 = Good, 2 = Fair, 3 = Moderate, 4 = Poor, 5 = Very Poor.
        components:
          $ref: '#/components/schemas/AirPollutionComponents'
  securitySchemes:
    appid:
      type: apiKey
      in: query
      name: appid