openapi: 3.0.3
info:
  title: Weather Underground PWS Forecast Historical 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: Historical
  description: Historical PWS observations and daily summaries
paths:
  /v2/pws/observations/hourly/7day:
    get:
      operationId: getHourlyObservations7Day
      summary: Get hourly observations for the past 7 days
      description: 'Returns hourly observation records for a specified Personal Weather Station over the past 7 days. Each record represents aggregated observations for a one-hour period.

        '
      tags:
      - Historical
      parameters:
      - $ref: '#/components/parameters/stationId'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/units'
      - $ref: '#/components/parameters/numericPrecision'
      responses:
        '200':
          description: Successful hourly observations response for 7 days
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationsListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/pws/dailysummary/7day:
    get:
      operationId: getDailySummary7Day
      summary: Get daily summary observations for the past 7 days
      description: 'Returns daily summary observation records for a specified Personal Weather Station over the past 7 days. Each record aggregates all observations from a single calendar day into min/max/average values.

        '
      tags:
      - Historical
      parameters:
      - $ref: '#/components/parameters/stationId'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/units'
      - $ref: '#/components/parameters/numericPrecision'
      responses:
        '200':
          description: Successful daily summary response for 7 days
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailySummaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/pws/history/all:
    get:
      operationId: getHistoryAllForDate
      summary: Get all historical observations for a specific date
      description: 'Returns all raw observation records for a specified Personal Weather Station on a given historical date. Provides the full granularity of data uploaded by the station for that date.

        '
      tags:
      - Historical
      parameters:
      - $ref: '#/components/parameters/stationId'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/units'
      - $ref: '#/components/parameters/numericPrecision'
      - name: date
        in: query
        required: true
        description: Date for historical observations in YYYYMMDD format
        schema:
          type: string
          pattern: ^\d{8}$
          example: '20240115'
      responses:
        '200':
          description: Successful historical all-observations response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationsListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/pws/history/daily:
    get:
      operationId: getHistoryDaily
      summary: Get daily historical observations for a date range
      description: 'Returns daily summary historical records for a specified Personal Weather Station within a date range. Supports up to approximately one month of daily summaries per request.

        '
      tags:
      - Historical
      parameters:
      - $ref: '#/components/parameters/stationId'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/units'
      - $ref: '#/components/parameters/numericPrecision'
      - name: startDate
        in: query
        required: true
        description: Start date of the range in YYYYMMDD format
        schema:
          type: string
          pattern: ^\d{8}$
          example: '20240101'
      - name: endDate
        in: query
        required: true
        description: End date of the range in YYYYMMDD format
        schema:
          type: string
          pattern: ^\d{8}$
          example: '20240131'
      responses:
        '200':
          description: Successful daily historical observations response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailySummaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DailySummaryResponse:
      type: object
      description: Response containing daily summary PWS observations
      properties:
        summaries:
          type: array
          items:
            $ref: '#/components/schemas/DailySummary'
          description: Array of daily summary records
    ObservationsListResponse:
      type: object
      description: Response containing a list of PWS observations over a time period
      properties:
        observations:
          type: array
          items:
            $ref: '#/components/schemas/Observation'
          description: Array of observation records ordered by time
    Observation:
      type: object
      description: A single weather observation record from a PWS station
      properties:
        stationID:
          type: string
          description: Unique identifier of the PWS station
          example: KCASARAT1
        obsTimeUtc:
          type: string
          format: date-time
          description: Observation timestamp in UTC
          example: '2024-01-15T18:32:00Z'
        obsTimeLocal:
          type: string
          description: Observation timestamp in local station time
          example: '2024-01-15 10:32:00'
        neighborhood:
          type: string
          description: Neighborhood or location name for the station
          example: Downtown
        softwareType:
          type: string
          description: Software used to upload data to the network
          example: WeatherBridge
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code of the station
          example: US
        solarRadiation:
          type: number
          description: Solar radiation intensity in W/m²
          example: 320.5
        lon:
          type: number
          format: double
          description: Station longitude in decimal degrees
          example: -122.419
        lat:
          type: number
          format: double
          description: Station latitude in decimal degrees
          example: 37.774
        uv:
          type: number
          description: UV index value
          example: 3.0
        winddir:
          type: integer
          description: Wind direction in degrees (0–360)
          example: 270
        windDirectionCardinal:
          type: string
          description: Wind direction as a compass cardinal or intercardinal point
          example: W
        humidity:
          type: integer
          description: Relative humidity percentage
          example: 68
        epoch:
          type: integer
          description: Unix timestamp of the observation
          example: 1705343520
        qcStatus:
          type: integer
          description: Quality control status flag (1 = passed QC)
          example: 1
        realtimeFrequency:
          type: integer
          nullable: true
          description: Realtime upload frequency in seconds, if applicable
          example: null
        imperial:
          $ref: '#/components/schemas/UnitMeasurements'
        metric:
          $ref: '#/components/schemas/UnitMeasurements'
        uk_hybrid:
          $ref: '#/components/schemas/UnitMeasurements'
        metric_si:
          $ref: '#/components/schemas/UnitMeasurements'
    UnitMeasurements:
      type: object
      description: 'Measurement values scoped to the requested unit system. The property name matches the units parameter value (e.g., "imperial", "metric", "uk_hybrid", or "metric_si").

        '
      properties:
        temp:
          type: number
          description: Air temperature
          example: 55.0
        heatIndex:
          type: number
          description: Apparent temperature accounting for humidity
          example: 55.0
        dewpt:
          type: number
          description: Dew point temperature
          example: 44.0
        windChill:
          type: number
          description: Wind chill temperature
          example: 55.0
        windSpeed:
          type: number
          description: Average wind speed
          example: 8.0
        windGust:
          type: number
          description: Peak wind gust speed
          example: 12.0
        pressure:
          type: number
          description: Atmospheric pressure (inHg for imperial, mbar for metric)
          example: 30.05
        precipRate:
          type: number
          description: Current precipitation rate per hour
          example: 0.0
        precipTotal:
          type: number
          description: Accumulated daily precipitation total
          example: 0.12
        elev:
          type: number
          description: Station elevation above sea level
          example: 52.0
    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
    DailySummaryMeasurements:
      type: object
      description: Daily summary measurements in the requested unit system
      properties:
        tempHigh:
          type: number
          description: Maximum temperature of the day
          example: 62.0
        tempLow:
          type: number
          description: Minimum temperature of the day
          example: 48.0
        tempAvg:
          type: number
          description: Average temperature of the day
          example: 55.0
        windspeedHigh:
          type: number
          description: Maximum wind speed of the day
          example: 18.0
        windspeedLow:
          type: number
          description: Minimum wind speed of the day
          example: 0.0
        windspeedAvg:
          type: number
          description: Average wind speed of the day
          example: 7.5
        windgustHigh:
          type: number
          description: Maximum wind gust of the day
          example: 22.0
        windgustLow:
          type: number
          description: Minimum wind gust of the day
          example: 0.0
        windgustAvg:
          type: number
          description: Average wind gust of the day
          example: 10.0
        dewptHigh:
          type: number
          description: Maximum dew point of the day
          example: 52.0
        dewptLow:
          type: number
          description: Minimum dew point of the day
          example: 39.0
        dewptAvg:
          type: number
          description: Average dew point of the day
          example: 46.0
        windchillHigh:
          type: number
          description: Maximum wind chill of the day
          example: 62.0
        windchillLow:
          type: number
          description: Minimum wind chill of the day
          example: 44.0
        windchillAvg:
          type: number
          description: Average wind chill of the day
          example: 53.0
        heatindexHigh:
          type: number
          description: Maximum heat index of the day
          example: 62.0
        heatindexLow:
          type: number
          description: Minimum heat index of the day
          example: 48.0
        heatindexAvg:
          type: number
          description: Average heat index of the day
          example: 55.0
        pressureMax:
          type: number
          description: Maximum atmospheric pressure of the day
          example: 30.12
        pressureMin:
          type: number
          description: Minimum atmospheric pressure of the day
          example: 29.98
        pressureTrend:
          type: number
          description: Pressure trend over the day
          example: -0.05
        precipRate:
          type: number
          description: Maximum precipitation rate of the day
          example: 0.25
        precipTotal:
          type: number
          description: Total accumulated precipitation for the day
          example: 0.48
    DailySummary:
      type: object
      description: 'A daily summary record aggregating all observations from a single calendar day for a PWS station.

        '
      properties:
        stationID:
          type: string
          description: Unique identifier of the PWS station
          example: KCASARAT1
        tz:
          type: string
          description: IANA timezone name of the station
          example: America/Los_Angeles
        obsTimeLocal:
          type: string
          description: Local date of the daily summary
          example: '2024-01-15 00:00:00'
        obsTimeUtc:
          type: string
          format: date-time
          description: UTC date of the daily summary
          example: '2024-01-15T08:00:00Z'
        epoch:
          type: integer
          description: Unix timestamp for the summary period
          example: 1705296000
        lat:
          type: number
          format: double
          description: Station latitude in decimal degrees
          example: 37.774
        lon:
          type: number
          format: double
          description: Station longitude in decimal degrees
          example: -122.419
        humidity:
          type: object
          description: Humidity summary statistics
          properties:
            min:
              type: integer
              description: Minimum humidity percentage for the day
              example: 45
            max:
              type: integer
              description: Maximum humidity percentage for the day
              example: 92
            avg:
              type: integer
              description: Average humidity percentage for the day
              example: 68
        imperial:
          $ref: '#/components/schemas/DailySummaryMeasurements'
        metric:
          $ref: '#/components/schemas/DailySummaryMeasurements'
  parameters:
    format:
      name: format
      in: query
      required: false
      description: Response format. Only JSON is currently supported.
      schema:
        type: string
        enum:
        - json
        default: json
    numericPrecision:
      name: numericPrecision
      in: query
      required: false
      description: 'When set to "decimal", numeric values are returned with decimal precision instead of rounded integers.

        '
      schema:
        type: string
        enum:
        - decimal
        example: decimal
    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
    stationId:
      name: stationId
      in: query
      required: true
      description: 'The PWS station identifier (e.g., KCASARAT1). Station IDs are assigned upon registration with Weather Underground''s PWS network.

        '
      schema:
        type: string
        example: KCASARAT1
  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

        '