OpenWeatherMap One Call API

openapi: 3.1.0
info:
  title: OpenWeatherMap Accumulated Parameters One Call API
  version: 2.5.0
  description: Returns accumulated temperature and accumulated precipitation totals over a user-specified historical time window. Targeted at agricultural and energy-sector applications. Available on Professional and Expert plans.
  contact:
    name: OpenWeather
    url: https://openweathermap.org/api/accumulated-parameters
  license:
    name: Creative Commons Attribution-ShareAlike 4.0 International
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://history.openweathermap.org/data/2.5/history
  description: Accumulated Parameters API base URL
security:
- appid: []
tags:
- name: One Call
  description: Unified timeline API with current, forecast, and historical weather plus alerts.
paths:
  /current:
    get:
      operationId: getOneCallCurrent
      summary: Current Weather From One Call
      description: Returns a single record with current conditions including temperature, humidity, pressure, wind, UV index, sunrise and sunset times, and weather descriptions for the supplied coordinates.
      tags:
      - One Call
      parameters:
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Lon'
      - $ref: '#/components/parameters/Units'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: One Call current weather response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OneCallCurrentResponse'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /timeline/1min:
    get:
      operationId: getOneCallTimelineOneMinute
      summary: One Minute Timeline
      description: Returns up to 60 records covering precipitation forecasts and government weather alerts at one-minute granularity.
      tags:
      - One Call
      parameters:
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Lon'
      - $ref: '#/components/parameters/Units'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: One Call one-minute timeline response.
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /timeline/15min:
    get:
      operationId: getOneCallTimelineFifteenMinute
      summary: Fifteen Minute Timeline
      description: Returns up to 50 records at 15-minute intervals including temperature, precipitation probability, and weather details.
      tags:
      - One Call
      parameters:
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Lon'
      - $ref: '#/components/parameters/Units'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: One Call 15-minute timeline response.
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /timeline/1h:
    get:
      operationId: getOneCallTimelineHour
      summary: Hourly Timeline With History
      description: Returns up to 20 records spanning 47 years of historical data and the next 48 hours of forecast at hourly granularity.
      tags:
      - One Call
      parameters:
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Lon'
      - $ref: '#/components/parameters/Units'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: One Call hourly timeline response.
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /timeline/1day:
    get:
      operationId: getOneCallTimelineDay
      summary: Daily Timeline With Aggregates
      description: Returns up to 10 records of daily aggregated weather data including moon phase, sunrise, sunset, and per-day summaries.
      tags:
      - One Call
      parameters:
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Lon'
      - $ref: '#/components/parameters/Units'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: One Call daily timeline response.
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
  /alert/{alert_id}:
    get:
      operationId: getOneCallAlert
      summary: Weather Alert Detail
      description: Returns a single weather alert record with event name, timing, description, and originating agency.
      tags:
      - One Call
      parameters:
      - name: alert_id
        in: path
        required: true
        description: Alert identifier returned by other One Call endpoints.
        schema:
          type: string
      - $ref: '#/components/parameters/Appid'
      responses:
        '200':
          description: Alert detail response.
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized.
        '404':
          description: Alert not found.
        '429':
          description: Too many requests.
components:
  parameters:
    Lat:
      name: lat
      in: query
      required: true
      description: Latitude in decimal degrees, range -90 to 90.
      schema:
        type: number
        format: float
    Lang:
      name: lang
      in: query
      required: false
      description: Localization language code.
      schema:
        type: string
    Appid:
      name: appid
      in: query
      required: true
      description: OpenWeather API key.
      schema:
        type: string
    Lon:
      name: lon
      in: query
      required: true
      description: Longitude in decimal degrees, range -180 to 180.
      schema:
        type: number
        format: float
    Units:
      name: units
      in: query
      required: false
      description: Units of measurement. standard, metric, or imperial.
      schema:
        type: string
        enum:
        - standard
        - metric
        - imperial
  schemas:
    OneCallCurrentResponse:
      type: object
      properties:
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        timezone:
          type: string
        timezone_offset:
          type: integer
        current:
          type: object
          properties:
            dt:
              type: integer
              format: int64
            sunrise:
              type: integer
              format: int64
            sunset:
              type: integer
              format: int64
            temp:
              type: number
              format: float
            feels_like:
              type: number
              format: float
            pressure:
              type: integer
            humidity:
              type: integer
            dew_point:
              type: number
              format: float
            uvi:
              type: number
              format: float
            clouds:
              type: integer
            visibility:
              type: integer
            wind_speed:
              type: number
              format: float
            wind_deg:
              type: integer
            weather:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                  main:
                    type: string
                  description:
                    type: string
                  icon:
                    type: string
  securitySchemes:
    appid:
      type: apiKey
      in: query
      name: appid