Historical collection | Part 2: Historical weather API

OpenWeather has been providing consistent and accurate data of current weather, forecasts and weather history for many years.
Aiming to simplify the process of obtaining data we created Historical weather data collection, a flexible and unique combination of our products (including APIs).

This article describes one of these products – the Historical weather API, an advanced solution for requesting multiple locations with a shallow data depth.

What we offer

The Historical weather API is designed to provide hourly historical weather data for more than 37k cities with basic parameters: Temperature, Pressure, Humidity, Wind, Precipitation and Clouds.
All weather data are delivered in the standard JSON format.
Several package options are available for subscribers: Starter – 1 month of historical data, Medium – 1 year of historical data. Should you require a longer period of historical data contact us at info@openweathermap.org and we will develop a plan that works for you.

Historical weather API call

Various parameters can be passed when making an API call: city ID, city name and geographic coordinates.
If you pass specific coordinates to the API the data will return for the nearest city available in our database.

Please, use the following parameters:

id - city ID
q – comma-separated city name and country code, ISO 3166 country code
lat, lon - location coordinates

The API template below allows the user to receive all available hourly data within the start-end interval.
http://history.openweathermap.org/data/2.5/history/city?[location]&type=hour&start={start}&end={end}&appid={YOUR_API_KEY}

Another type of request allows the user to obtain the required amount (cnt) of hourly data values since the start timestamp:
http://history.openweathermap.org/data/2.5/history/city?[location]&type=hour&start={start}&cnt={cnt}&appid={YOUR_API_KEY}

API call parameters:

location - city ID ( id={id} ) or city name ( q={city ID}, {country code} ) or coordinates ( lat={lat}&lon={lon} )
type – set it to 'hour'
start - start date in UTC unix time format, e.g. start=1369728000
end - end date in UTC unix time format, e.g. end=1369789200
cnt – requested amount of hourly data

Examples of API calls:

Using city ID: http://history.openweathermap.org/data/2.5/history/city?id=2885679&type=hour&appid={YOUR_API_KEY}

Using city name:  http://history.openweathermap.org/data/2.5/history/city?q=London,UK&appid={YOUR_API_KEY}

Using coordinates: http://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87.65&appid={YOUR_API_KEY}

The maximum depth of historical data in an API response is one week for the Starter and Medium packages.
If data depth is requested for more than one week, the API will return historical data only for the first week from the start date.
Make multiple calls to retrieve historical data for more than one week.

Weather parameters in API response

Available values of hourly data returned by the History API are temperature, pressure, humidity, wind, precipitation and cloud cover.

List of all API parameters and units is described at https://openweathermap.org/weather-data
List of weather condition codes and their icons is available at https://openweathermap.org/weather-conditions
including levels of thunderstorm, rainfall, snowfall, cloud cover; extreme weather events like tornado, hurricane etc.

Example of API response (JSON):

Parameters:

• message - internal parameter
• cod - internal parameter
• city_id - city ID
• calctime - internal parameter
• list
  • dt – forecast time in UTC Unix format
  • main
    • main.temp – the temperature value, given in Kelvin only.
    • main.feels_like - human perception of temperature. Units: Kelvin by default, Celsius (metric), Fahrenheit (imperial).
    • main.pressure - atmospheric pressure at sea level if available, or at ground level, hPa
    • main.humidity - humidity, %
    • main.temp_min – minimum temperature within a large city or a megalopolis (optional parameter). The temperature is provided only in Kelvin.
    • main.temp_max - maximum temperature within a large city or a megalopolis (optional parameter). The temperature is provided only in Kelvin.
    • main.sea_level – atmospheric pressure at sea level, hPa
    • main.grnd_level – atmospheric pressure at ground level, hPa
  • wind
    • wind.speed - wind speed. Unit: m/s.
    • wind.deg - wind direction and degrees
  • clouds
    • clouds.all – cloud cover, %
  • rain
    • rain.1h - rainfall volume for the last hour
    • rain.3h - rainfall volume for the last 3 hours
  • snow
    • snow.1h - snowfall volume for the last hour
    • snow.3h - snowfall volume for the last 3 hours
  • weather
    • weather.id - weather condition id
    • weather.main – weather description
    • weather.description – detailed weather description
    • weather.icon - icon id of weather condition

Some API parameters may be omitted, as corresponding weather conditions may not occur at the time of measurement for the selected city or location. Only actual data are provided in the API response.

See also:
Historical collection | Part 1: History API, Statistical API and History Bulks
Historical collection | Part 3: History Bulk

Please, feel free to contact us with any questions and suggestions at info@opernweathermap.org.