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 IDq – comma-separated city name and country code, ISO 3166 country codelat, 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=1369728000end - end date in UTC unix time format, e.g. end=1369789200cnt – 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-dataList of weather condition codes and their icons is available at https://openweathermap.org/weather-conditionsincluding 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
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 BulksHistorical collection | Part 3: History Bulk
Please, feel free to contact us with any questions and suggestions at info@opernweathermap.org.