History API Full archive

This product provides the full archive of historical weather data by chosen location from 1 January 1979 till now. Weather data are available with 1-hour step.

There are 3 simple steps to get the historical archive for your location:

  1. Create a unique location via API call - section 1. Once you create your location, its historical weather data start preparing automatically.
  2. Check your location list to make sure that weather data for your new location has been prepared - section 2.
  3. As soon as the weather data for your new location has been prepared, then you can start requesting historical data for it - section 3.

1. How to add a location to download list

To activate loading your data you should add your location to the download list by making an API call according to the following rules.

API call

http://history.openweathermap.org/data/3.0/history/locations/create?lat={lat}&lon={lon}&appid={API key}
Parameters
lat required Latitude. If you need a geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API
lon required Longitude. If you need a geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API
appid required Your unique API key (you can always find it on your account page under the "API key" tab)

Example of API call

http://history.openweathermap.org/data/3.0/history/locations/create?lat=51.8080&lon=-0.1257&appid={API key} 
                        
{
    "id": "53506193580c9bda6c38a1c6a67f5599", //location id
    "lat": 52.808,
    "lon": -0.1257,
    "start": 283996800,
    "end": 1597104000,
    "created_at": "2020-08-11T15:51:23.377Z",
    "status": "calculating"
},
Errors
422000 An incorrect lat, lon or an already existing location was entered

Please note:

  • When creating unique locations, coordinates are rounded to 4 decimal places.
  • You cannot add the same location twice.
  • When you add a new location, our system starts to prepare historical weather data. Due to the volume of this archive, preparing weather data archive by your location can be relatively time-consuming. It can take up to 30-40 min before data becomes available.
  • To check the status of the newly added location, please see section #2 below.
  • Historical data will not be recalculated after the first calculation.

2. How to get a list of all added locations and status of new locations

Before trying to get historical weather data by your created location (read the section 1), please make sure that weather data has been successfully downloaded for your location. To check the statuses of your locations please use this section.

API call

http://history.openweathermap.org/data/3.0/history/locations?appid={API key}
Location statuses
calculating Data for the new location is processing. Please wait.
done Calculation for the new location has been successful. You can request historical weather data. Please read section 3 of the current document to learn more.
failed Internal error. Please contact our support team.

3. How to get historical data for added location

API call

http://history.openweathermap.org/data/3.0/history/result?id={location_id}&start={start_date}&end={end_date}&appid={API key}
Parameters
location_id required Location ID, which you received when adding your unique location (please see section 1 of this documentation)
start_date required Any date from 1 January 1979 till 23:59 of the previous day, Unix, UTC
end_date required Any date from 1 January 1979 till 23:59 of the previous day, Unix, UTC
appid required Your unique API key (you can always find it on your account page under the "API key" tab)

To avoid receiving errors in the API response, please specify a time period of requested historical data less than 1 year in one API call.

Example of the API response: 
                        
{ 
    "id": "7466e40670b7eccdd6c27cf9a78ea286", 
    "cnt": 278, 
    "list": [ 
        { "dt": 283996800, 
        "main": { 
            "temp": 268.6, 
            "feels_like": 261.48, 
            "pressure": 1010, 
            "humidity": 85, 
            "temp_min": 268.15, 
            "temp_max": 269.121 
            }, 
            "wind": { 
                "speed": 6.2, 
                "deg": 350 
                }, 
            "clouds": { 
                    "all": 20 
                    }, 
            "weather": [ 
                        { 
                        "id": 801, 
                        "main": "Clouds", 
                        "description": "few clouds", 
                        "icon": "02n" 
                        } 
                    ] 
                }, 
                … 
            ] 
        }
Errors
404000 You have specified an ID of non-existent location
404001 Calculation process has not yet ended, please see paragraph #2 of the current document)

Historical data in the API response

If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response.

Fields in API Response

  • id Location ID
  • cnt Technical field
  • list
    • dt Time of data calculation, unix, UTC
    • main
      • main.temp Temperature, Kelvins
      • main.feels_like Temperature, Kelvins. This temperature parameter accounts for the human perception of weather
      • main.pressure Atmospheric pressure, hPa
      • main.humidity Humidity, %
      • main.temp_min Minimum temperature within a large city or a megalopolis (optional parameter), Kelvin
      • main.temp_max Maximum temperature within a large city or a megalopolis (optional parameter), Kelvins
    • wind
      • wind.speed Wind speed. Unit: meter/sec.
      • wind.deg Wind direction, degrees (meteorological)
    • clouds
      • clouds.all Cloudiness, %
    • rain
      • rain.1h Rain volume for the last 1 hour
    • snow
      • snow.1h Snow volume for the last 1 hour
    • weather (Full list of weather conditions)
      • weather.id Weather condition id
      • weather.main Group of weather parameters (Rain, Snow, Clouds etc.)
      • weather.description Weather condition within the group. Please find more here
      • weather.icon Weather icon id

List of weather condition codes

List of weather condition codes with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.)

We use cookies to personalize content and to analyze our traffic. Please decide if you are willing to accept cookies from our website.
Advanced Settings