History API Full Archive

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:

Create a unique location via API call - section 1. Once you create your location, its historical weather data start preparing automatically.
Check your location list to make sure that weather data for your new location has been prepared - section 2.
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 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.

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

We provide a broad variety of products such as One Call API 3.0, Solar Irradiance & Energy Prediction service, Road Risk API, Air Pollution API and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our product list page and find more info in the product documentation and pricing pages.

List of weather condition codes

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

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)

{ "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

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.

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)

Example of 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)