Weather Underground Forecast API
Weather forecasts based on PWS location
OpenAPI Specification
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
'