openapi: 3.0.3
info:
  title: Weather Underground PWS Forecast API
  description: 'REST API for Personal Weather Station (PWS) data provided by Weather Underground (hosted at api.weather.com). Provides current conditions, daily summaries, hourly and daily historical records, 5-day forecasts, and station location lookup. Access requires a free API key issued to registered PWS contributors.

    '
  version: 2.0.0
  contact:
    url: https://www.wunderground.com/member/api-keys
  termsOfService: https://www.wunderground.com/member/api-keys
  x-api-evangelist-ratings:
    design: 7
    documentation: 5
    authentication: 7
    openapi: 1
servers:
- url: https://api.weather.com
  description: Weather Underground / The Weather Company API server
security:
- apiKey: []
tags:
- name: Forecast
  description: Weather forecasts based on PWS location
paths:
  /v3/wx/forecast/daily/5day:
    get:
      operationId: get5DayForecast
      summary: Get 5-day daily weather forecast
      description: 'Returns a 5-day daily weather forecast for a location specified by geocode (latitude and longitude). Typically used in conjunction with PWS station coordinates obtained from the observations endpoint.

        '
      tags:
      - Forecast
      parameters:
      - name: geocode
        in: query
        required: true
        description: 'Latitude and longitude as a comma-separated pair (e.g., 37.774,-122.419)

          '
        schema:
          type: string
          example: 37.774,-122.419
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/units'
      - name: language
        in: query
        required: false
        description: 'Language code for forecast text (e.g., en-US, fr-FR)

          '
        schema:
          type: string
          default: en-US
          example: en-US
      responses:
        '200':
          description: Successful 5-day forecast response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForecastResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    format:
      name: format
      in: query
      required: false
      description: Response format. Only JSON is currently supported.
      schema:
        type: string
        enum:
        - json
        default: json
    units:
      name: units
      in: query
      required: false
      description: 'Unit system for measurement values. e = Imperial (English), m = Metric, s = SI (metric with Pa pressure), h = Hybrid (UK)

        '
      schema:
        type: string
        enum:
        - e
        - m
        - s
        - h
        default: m
        example: e
  schemas:
    ForecastResponse:
      type: object
      description: 5-day daily weather forecast response
      properties:
        calendarDayTemperatureMax:
          type: array
          items:
            type: integer
            nullable: true
          description: Maximum calendar day temperatures for each day
          example:
          - 62
          - 58
          - 65
          - 60
          - 55
        calendarDayTemperatureMin:
          type: array
          items:
            type: integer
            nullable: true
          description: Minimum calendar day temperatures for each day
          example:
          - 48
          - 45
          - 50
          - 47
          - 42
        dayOfWeek:
          type: array
          items:
            type: string
          description: Day of week names for each forecast day
          example:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
        expirationTimeUtc:
          type: array
          items:
            type: integer
          description: Unix timestamps when each day's forecast expires
        moonPhase:
          type: array
          items:
            type: string
          description: Moon phase description for each day
          example:
          - Waxing Gibbous
        moonriseTimeLocal:
          type: array
          items:
            type: string
            nullable: true
          description: Local moonrise time for each day
        moonsetTimeLocal:
          type: array
          items:
            type: string
            nullable: true
          description: Local moonset time for each day
        narrative:
          type: array
          items:
            type: string
          description: Overall narrative forecast text for each day
          example:
          - Mostly cloudy. Highs in the low 60s.
        qpf:
          type: array
          items:
            type: number
            nullable: true
          description: Quantitative precipitation forecast for each day
          example:
          - 0.1
          - 0.0
          - 0.25
          - 0.05
          - 0.0
        qpfSnow:
          type: array
          items:
            type: number
            nullable: true
          description: Quantitative snow precipitation forecast for each day
          example:
          - 0.0
          - 0.0
          - 0.0
          - 0.0
          - 0.0
        sunriseTimeLocal:
          type: array
          items:
            type: string
            nullable: true
          description: Local sunrise time for each day
          example:
          - 2024-01-15T07:23:00-0800
        sunsetTimeLocal:
          type: array
          items:
            type: string
            nullable: true
          description: Local sunset time for each day
          example:
          - 2024-01-15T17:12:00-0800
        temperatureMax:
          type: array
          items:
            type: integer
            nullable: true
          description: Maximum temperature for each forecast day
          example:
          - 62
          - 58
          - 65
          - 60
          - 55
        temperatureMin:
          type: array
          items:
            type: integer
            nullable: true
          description: Minimum temperature for each forecast day
          example:
          - 48
          - 45
          - 50
          - 47
          - 42
        validTimeLocal:
          type: array
          items:
            type: string
          description: Local valid time for each forecast day
          example:
          - 2024-01-15T07:00:00-0800
        validTimeUtc:
          type: array
          items:
            type: integer
          description: Unix timestamps for valid time of each forecast day
          example:
          - 1705327200
        daypart:
          type: array
          items:
            $ref: '#/components/schemas/ForecastDaypart'
          description: Detailed forecast data for each day part (day/night pairs)
    ErrorResponse:
      type: object
      description: Error response from the API
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: Error code
                    example: NOT-AUTHORIZED
                  message:
                    type: string
                    description: Human-readable error message
                    example: Not Authorized
    ForecastDaypart:
      type: object
      description: Forecast data for a specific day part (day or night)
      properties:
        cloudCover:
          type: array
          items:
            type: integer
            nullable: true
          description: Cloud cover percentage for each day part
          example:
          - 40
          - 20
          - 55
          - 30
        iconCode:
          type: array
          items:
            type: integer
            nullable: true
          description: Weather icon code for each day part
          example:
          - 28
          - 31
          - 26
          - 33
        iconCodeExtend:
          type: array
          items:
            type: integer
            nullable: true
          description: Extended icon code for each day part
        narrative:
          type: array
          items:
            type: string
            nullable: true
          description: Text narrative forecast for each day part
          example:
          - Mostly cloudy. High 62F.
          - Clear. Low 48F.
        precipChance:
          type: array
          items:
            type: integer
            nullable: true
          description: Probability of precipitation percentage for each day part
          example:
          - 20
          - 10
          - 40
          - 15
        precipType:
          type: array
          items:
            type: string
            nullable: true
          description: Type of precipitation expected for each day part
          example:
          - rain
          - none
        temperature:
          type: array
          items:
            type: integer
            nullable: true
          description: Temperature for each day part
          example:
          - 62
          - 48
          - 58
          - 45
        windDirection:
          type: array
          items:
            type: integer
            nullable: true
          description: Wind direction in degrees for each day part
          example:
          - 270
          - 250
        windDirectionCardinal:
          type: array
          items:
            type: string
            nullable: true
          description: Cardinal wind direction for each day part
          example:
          - W
          - WSW
        windPhrase:
          type: array
          items:
            type: string
            nullable: true
          description: Text description of wind conditions for each day part
          example:
          - Winds W at 10 to 15 mph.
        windSpeed:
          type: array
          items:
            type: integer
            nullable: true
          description: Wind speed for each day part
          example:
          - 12
          - 8
  responses:
    Unauthorized:
      description: 'Authentication failed. The API key is missing, invalid, or not authorized for the requested station or endpoint.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: 'The requested station ID was not found or has no data for the specified date range.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: apiKey
      description: 'API key issued to registered PWS contributors via https://www.wunderground.com/member/api-keys

        '