Local History API

Access historical weather conditions from 1st July 2008 to present — hourly and 3-hourly intervals, astronomy data, and full weather conditions for any city, town or location worldwide.

Introduction

The Local Historical (Past) Weather API lets you retrieve observed weather data going back to 1st July 2008. You can query a single date or a date range within the same month, and choose hourly intervals from 1-hourly through to daily averages. The API returns temperature, precipitation, weather descriptions, wind speed and direction, visibility, pressure, humidity, and astronomy data.

Data from 1st July 2008 onwards

Hourly & 3-hourly intervals

Astronomy data included

JSON / XML / JSON-P output

You can specify location by any of the following:

City or town name
IP address
UK postcode
Canada postal code
US zipcode
Latitude and longitude (decimal degrees)

Need more than 3 months of history or bulk data downloads? Visit the Buy History Data section for extended access options.

HTTP Methods

The Local History API supports GET requests only. Both HTTP and HTTPS base URLs are available:

Base URLs

# HTTP
http://api.worldweatheronline.com/premium/v1/past-weather.ashx
 
# HTTPS (recommended)
https://api.worldweatheronline.com/premium/v1/past-weather.ashx

Example Request

https://api.worldweatheronline.com/premium/v1/past-weather.ashx
  ?key=YOUR_API_KEY
  &q=London
  &date=2023-06-01
  &enddate=2023-06-03
  &tp=3
  &format=json

Querystring Parameters

The table below lists all supported request parameters. Required parameters are marked REQ and optional ones OPT.

Parameter	Description	Values / Default
q REQ	Location query. See the q parameter table for accepted formats.	—
extra OPT	Include additional fields in the response. See the extra parameter table.	—
date REQ	The date for which to return historical weather data.	`yyyy-MM-dd` e.g. `2009-07-20`
enddate OPT	End of a date range. Use to retrieve weather across multiple consecutive days. Important: `enddate` must fall within the same month and year as `date`.	`yyyy-MM-dd` e.g. `2009-07-22`
includelocation OPT	Return the nearest weather observation point for the given query (postcode, zipcode, lat/lon).	`yes` / `no` (default)
tp OPT	Hourly interval for the data. Options: 1 hour, 3-hourly, 6-hourly, 12-hourly (day/night) or 24-hourly (day average).	`1` / `3` (default) / `6` / `12` / `24`
format OPT	Output format.	`xml` (default) / `json`
callback OPT	Callback function name for JSONP. Only applicable when `format=json`.	e.g. `callback=myFunc`
key REQ	Your API authentication key. Get a free key here.	—

q Parameter Values

The q parameter accepts multiple input types for location:

Location Type	Format	Examples
City or town name	City Name, City Name + State (US), City Name + Country	`q=New+York`, `q=New+York,ny`, `q=London,united+kingdom`
IP address	`XXX.XXX.XXX.XXX`	`q=101.25.32.325`
UK / Canada postcode or US zipcode	Postal or zip code format	`q=SW1`, `q=90201`
Latitude and longitude	Decimal degrees: `XX.XXX,XX.XXX`	`q=48.834,2.394`

extra Parameter Values

The extra parameter adds optional fields to hourly entries. Multiple values can be combined with commas.

Value	Effect on Response
isDayTime	Adds an `isDayTime` field to each hourly entry: `yes` for daytime, `no` for night. Only works with 3-hourly, 6-hourly or 12-hourly intervals.
utcDateTime	Time intervals are displayed in UTC format instead of local date and time.

HTTP Response

Responses are available in XML or JSON. The root element is data, which contains the following child elements:

Element	Description
request	Echoes the type and parsed query of the request.
nearest_area	The nearest area resolved for the given query, including coordinates and place names.
weather	Historical weather data for each requested day, including hourly breakdowns and astronomy.

request element

Field	Description	Type
type	The type of location request: `City`, `LatLon`, `Postcode`, `Zipcode`, `IP`, etc.	String
query	The location query as parsed by the API.	String

nearest_area element

Information about the nearest observation point in the database from which the historical data was taken.

Field	Description	Type
areaName	Name of the nearest location in the database.	String
country	Country name.	String
region	Region, state or county.	String
latitude	Latitude in decimal degrees.	Float
longitude	Longitude in decimal degrees.	Float

weather element

Each item in the weather array represents a single day of historical data.

Field	Description	Type
date	Date of the historical record (`yyyy-MM-dd`).	Date
maxtempC	Maximum temperature for the day in degrees Celsius.	Integer
maxtempF	Maximum temperature for the day in degrees Fahrenheit.	Integer
mintempC	Minimum temperature for the day in degrees Celsius.	Integer
mintempF	Minimum temperature for the day in degrees Fahrenheit.	Integer
uvIndex	UV index for the day.	Integer
totalSnow_cm	Total snowfall amount for the day in centimetres.	Float
sunHour	Total hours of sunshine for the day.	Float
astronomy	Sunrise, sunset, moonrise, moonset, moon phase and illumination. See astronomy element.	Object
hourly	Array of hourly weather observations for this day. See hourly element.	Array

astronomy element

Sun and moon rise/set times and moon phase for the day.

Field	Description	Type
sunrise	Local sunrise time.	Time (`hh:mm AM/PM`), e.g. `05:41 AM`
sunset	Local sunset time.	Time (`hh:mm AM/PM`), e.g. `06:30 PM`
moonrise	Local moonrise time.	Time (`hh:mm AM/PM`), e.g. `01:49 AM`
moonset	Local moonset time.	Time (`hh:mm AM/PM`), e.g. `06:43 PM`
moon_phase	Moon phase. One of: `New Moon`, `Waxing Crescent`, `First Quarter`, `Waxing Gibbous`, `Full Moon`, `Waning Gibbous`, `Last Quarter`, `Waning Crescent`.	String
moon_illumination	Moon illumination as a percentage (0–100).	Integer (%)

hourly element

Each entry in the hourly array covers one time interval within the day. The number of entries depends on the tp parameter.

Field	Description	Type
time	Local time of the interval in `hmm` format, e.g. `100` = 1:00 AM, `1500` = 3:00 PM.	String
tempC	Temperature in degrees Celsius.	Integer
tempF	Temperature in degrees Fahrenheit.	Integer
FeelsLikeC	Feels-like temperature in degrees Celsius.	Integer
FeelsLikeF	Feels-like temperature in degrees Fahrenheit.	Integer
HeatIndexC	Heat index temperature in degrees Celsius.	Integer
HeatIndexF	Heat index temperature in degrees Fahrenheit.	Integer
DewPointC	Dew point temperature in degrees Celsius.	Integer
DewPointF	Dew point temperature in degrees Fahrenheit.	Integer
WindChillC	Wind chill temperature in degrees Celsius.	Integer
WindChillF	Wind chill temperature in degrees Fahrenheit.	Integer
windspeedMiles	Wind speed in miles per hour.	Integer
windspeedKmph	Wind speed in kilometres per hour.	Integer
windspeedKnots	Wind speed in knots.	Integer
windspeedMeterSec	Wind speed in metres per second.	Integer
WindGustMiles	Wind gust speed in miles per hour.	Integer
WindGustKmph	Wind gust speed in kilometres per hour.	Integer
winddirDegree	Wind direction in degrees (0–360).	Integer
winddir16Point	Wind direction as a 16-point compass abbreviation (e.g. `N`, `NNE`).	String
weatherCode	Weather condition code. See Weather Icons & Codes.	Integer
weatherDesc	Text description of the weather condition.	String
weatherIconUrl	URL to the weather condition icon image.	URL
precipMM	Precipitation amount in millimetres.	Float
precipInches	Precipitation amount in inches.	Float
humidity	Relative humidity as a percentage (0–100).	Integer
visibility	Visibility in kilometres.	Integer
visibilityMiles	Visibility in miles.	Integer
pressure	Atmospheric pressure in millibars (mb).	Integer
pressureInches	Atmospheric pressure in inches of mercury.	Integer
cloudcover	Cloud cover as a percentage (0–100).	Integer

Examples

Example 1 — Single Day, 3-Hourly (JSON)

Retrieve 3-hourly historical weather for London on 1st June 2023, returned as JSON:

Request URL

https://api.worldweatheronline.com/premium/v1/past-weather.ashx
  ?key=YOUR_API_KEY
  &q=London
  &date=2023-06-01
  &tp=3
  &format=json

Abbreviated JSON response:

Response (JSON, abbreviated)

{
  "data": {
    "request": [{
      "type": "City",
      "query": "London, City of London, Greater London, United Kingdom"
    }],
    "weather": [{
      "date":       "2023-06-01",
      "maxtempC":   "21",
      "mintempC":   "13",
      "uvIndex":    "5",
      "sunHour":    "9.4",
      "totalSnow_cm": "0.0",
      "astronomy": [{
        "sunrise":          "04:49 AM",
        "sunset":           "09:07 PM",
        "moonrise":         "03:09 PM",
        "moonset":          "01:27 AM",
        "moon_phase":       "Waxing Gibbous",
        "moon_illumination": "79"
      }],
      "hourly": [
        {
          "time":           "0",
          "tempC":          "14",
          "windspeedKmph":  "15",
          "winddir16Point": "WSW",
          "weatherDesc":    "Clear",
          "precipMM":       "0.0",
          "humidity":       "68"
        },
        /* ... more hourly entries ... */
      ]
    }]
  }
}

Example 2 — Date Range, Daily Average (XML)

Retrieve daily average weather for Paris across a 5-day range in July 2022, using the lat/lon query:

Request URL

https://api.worldweatheronline.com/premium/v1/past-weather.ashx
  ?key=YOUR_API_KEY
  &q=48.85,2.35
  &date=2022-07-10
  &enddate=2022-07-14
  &tp=24
  &format=xml

The enddate must be in the same month and year as date. To retrieve data spanning multiple months, make separate requests per month.

Test any request live in the API Explorer — just enter your key and parameters, no code needed.