Historical weather API

We provide hourly historical weather data for cities via History API. Availability of hourly historical data depends on a type of your subscription.

You can also download this data in JSON or CSV format - please read History Bulk and History Forecast Bulk.

Hourly historical data for cities

By city name

Call historical data by city name.

API call

http://history.openweathermap.org/data/2.5/history/city?q={city ID},{country code}&type=hour&start={start}&end={end}&appid={API key}
http://history.openweathermap.org/data/2.5/history/city?q={city ID},{country code}&type=hour&start={start}&cnt={cnt}&appid={API key}
Parameters
q required City name, state code and country code divided by comma, use ISO 3166 country codes.

You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations. Learn more
type required type of the call, keep this parameter in the API call as hour
appid required Your unique API key (you can always find it on your account page under the "API key" tab)
start optional Start date (unix time, UTC time zone), e.g. start=1369728000
end optional End date (unix time, UTC time zone), e.g. end=1369789200
cnt optional A number of timestamps in response (one per hour, can be used instead of end)

Example of API call

http://history.openweathermap.org/data/2.5/history/city?q=London,UK&appid={API key} 
                        
{
   "message":"",
   "cod":"200",
   "city_id":2643743,
   "calctime":0.0875,
   "cnt":3,
   "list":[
   {
      "main":{
         "temp":279.946,
         "temp_min":279.946,
         "temp_max":279.946,
         "pressure":1016.76,
         "sea_level":1024.45,
         "grnd_level":1016.76,
         "humidity":100
      },
      "wind":{
         "speed":4.59,
         "deg":163.001
      },
      "clouds":{
         "all":92
      },
      "weather":[
         {
            "id":500,
            "main":"Rain",
            "description":"light rain",
            "icon":"10n"
         }
      ],
      "rain":{
         "3h":2.69
      },
      "dt":1485717216
   },
   {
      "main":{
         "temp":282.597,
         "temp_min":282.597,
         "temp_max":282.597,
         "pressure":1012.12,
         "sea_level":1019.71,
         "grnd_level":1012.12,
         "humidity":98
      },
      "wind":{
         "speed":4.04,
         "deg":226
      },
      "clouds":{
         "all":92
      },
      "weather":[
         {
            "id":500,
            "main":"Rain",
            "description":"light rain",
            "icon":"10n"
         }
      ],
      "rain":{
         "3h":0.405
      },
      "dt":1485745061
   },
   {
      "main":{
         "temp":279.38,
         "pressure":1011,
         "humidity":93,
         "temp_min":278.15,
         "temp_max":280.15
      },
      "wind":{
         "speed":2.6,
         "deg":30
      },
      "clouds":{
         "all":90
      },
      "weather":[
         {
            "id":701,
            "main":"Mist",
            "description":"mist",
            "icon":"50d"
         },
         {
            "id":741,
            "main":"Fog",
            "description":"fog",
            "icon":"50d"
         }
      ],
      "dt":1485768552
   }
   ]
}
There is a possibility to receive a central district of the city/town with its own parameters (geographic coordinates/id/name) in API response. Please see the example below.
http://history.openweathermap.org/data/2.5/history/city?q=Munchen,DE&appid={API key} 
                        
{
   "message":"",
   "cod":"200",
   "city_id":2643743,
   "calctime":0.0875,
   "cnt":3,
   "list":[
   {
      "main":{
         "temp":279.946,
         "temp_min":279.946,
         "temp_max":279.946,
         "pressure":1016.76,
         "sea_level":1024.45,
         "grnd_level":1016.76,
         "humidity":100
      },
      "wind":{
         "speed":4.59,
         "deg":163.001
      },
      "clouds":{
         "all":92
      },
      "weather":[
         {
            "id":500,
            "main":"Rain",
            "description":"light rain",
            "icon":"10n"
         }
      ],
      "rain":{
         "3h":2.69
      },
      "dt":1485717216
   },
   {
      "main":{
         "temp":282.597,
         "temp_min":282.597,
         "temp_max":282.597,
         "pressure":1012.12,
         "sea_level":1019.71,
         "grnd_level":1012.12,
         "humidity":98
      },
      "wind":{
         "speed":4.04,
         "deg":226
      },
      "clouds":{
         "all":92
      },
      "weather":[
         {
            "id":500,
            "main":"Rain",
            "description":"light rain",
            "icon":"10n"
         }
      ],
      "rain":{
         "3h":0.405
      },
      "dt":1485745061
   },
   {
      "main":{
         "temp":279.38,
         "pressure":1011,
         "humidity":93,
         "temp_min":278.15,
         "temp_max":280.15
      },
      "wind":{
         "speed":2.6,
         "deg":30
      },
      "clouds":{
         "all":90
      },
      "weather":[
         {
            "id":701,
            "main":"Mist",
            "description":"mist",
            "icon":"50d"
         },
         {
            "id":741,
            "main":"Fog",
            "description":"fog",
            "icon":"50d"
         }
      ],
      "dt":1485768552
   }
   ]
}

By city ID

Call historical data by city ID. API responds with exact result.

The list of city IDs can be downloaded here.

API calls

http://history.openweathermap.org/data/2.5/history/city?id={id}&type=hour&start={start}&end={end}&appid={API key}
http://history.openweathermap.org/data/2.5/history/city?id={id}&type=hour&start={start}&cnt={cnt}&appid={API key}
Parameters
id required City ID. The list of city IDs 'city.list.json.gz' can be downloaded here.
type required Type of the call, keep this parameter in the API call as hour
appid required Your unique API key (you can always find it on your account page under the "API key" tab)
start optional Start date (unix time, UTC time zone), e.g. start=1369728000
end optional End date (unix time, UTC time zone), e.g. end=1369789200
cnt optional Amount of returned data (one per hour, can be used instead of end)

Example of API call

http://history.openweathermap.org/data/2.5/history/city?id=2885679&type=hour&appid={API key} 
                        
{
   "message":"",
   "cod":"200",
   "city_id":2885679,
   "calctime":0.0823,
   "cnt":3,
   "list":[
   {
      "main":{
         "temp":266.052,
         "temp_min":266.052,
         "temp_max":266.052,
         "pressure":957.86,
         "sea_level":1039.34,
         "grnd_level":957.86,
         "humidity":90
      },
      "wind":{
         "speed":1.16,
         "deg":139.502
      },
      "clouds":{
         "all":0
      },
      "weather":[
         {
            "id":800,
            "main":"Clear",
            "description":"Sky is Clear",
            "icon":"01n"
         }
      ],
      "dt":1485722804
   },
   {
      "main":{
         "temp":263.847,
         "temp_min":263.847,
         "temp_max":263.847,
         "pressure":955.78,
         "sea_level":1037.43,
         "grnd_level":955.78,
         "humidity":91
      },
      "wind":{
         "speed":1.49,
         "deg":159
      },
      "clouds":{
         "all":0
      },
      "weather":[
         {
            "id":800,
            "main":"Clear",
            "description":"Sky is Clear",
            "icon":"01n"
         }
      ],
      "dt":1485749608
   },
   {
      "main":{
         "temp":274.9,
         "pressure":1019,
         "temp_min":274.15,
         "temp_max":275.15,
         "humidity":88
      },
      "wind":{
         "speed":1,
         "deg":0
      },
      "clouds":{
         "all":76
      },
      "weather":[
         {
            "id":500,
            "main":"Rain",
            "description":"light rain",
            "icon":"10d"
         }
      ],
      "dt":1485773778
   }
   ]
}
Only for Starter and Medium plans: The maximum historical data depth in one API response is one week.

If you specify a historical data depth more than one week in the request, you will receive a historical data only for first week from start date in one API response.

If you want to get the historical data depth more than one week, then please use several queries.

By geographic coordinates

Call historical data by geographic coordinates.

API call

http://history.openweathermap.org/data/2.5/history/city?lat={lat}&lon={lon}&type=hour&start={start}&end={end}&appid={API key}
http://history.openweathermap.org/data/2.5/history/city?lat={lat}&lon={lon}&type=hour&start={start}&cnt={cnt}&appid={API key}
Parameters
lat, lon required coordinates of the location of your interest
type required type of the call, keep this parameter in the API call as hour
appid required Your unique API key (you can always find it on your account page under the "API key" tab)
start optional Start date (unix time, UTC time zone), e.g. start=1369728000
end optional End date (unix time, UTC time zone), e.g. end=1369789200
cnt optional A number of timestamps in response (one per hour, can be used instead of end)

Example of API call

http://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87.65&appid={API key} 
                        
{
   "message":"",
   "cod":"200",
   "city_id":4887398,
   "calctime":0.0863,
   "cnt":4,
   "list":[
   {
      "main":{
         "temp":268.987,
         "temp_min":268.987,
         "temp_max":268.987,
         "pressure":1001.11,
         "sea_level":1024.68,
         "grnd_level":1001.11,
         "humidity":100
      },
      "wind":{
         "speed":5.06,
         "deg":291.002
      },
      "clouds":{
         "all":48
      },
      "weather":[
         {
            "id":802,
            "main":"Clouds",
            "description":"scattered clouds",
            "icon":"03d"
         }
      ],
      "dt":1485703465
   },
   {
      "main":{
         "temp":268.097,
         "temp_min":268.097,
         "temp_max":268.097,
         "pressure":1003.57,
         "sea_level":1027.08,
         "grnd_level":1003.57,
         "humidity":100
      },
      "wind":{
         "speed":8.56,
         "deg":314.007
      },
      "clouds":{
         "all":44
      },
      "weather":[
         {
            "id":802,
            "main":"Clouds",
            "description":"scattered clouds",
            "icon":"03d"
         }
      ],
      "dt":1485730032
   },
   {
      "main":{
         "temp":266.787,
         "temp_min":266.787,
         "temp_max":266.787,
         "pressure":1005.73,
         "sea_level":1029.63,
         "grnd_level":1005.73,
         "humidity":100
      },
      "wind":{
         "speed":6.79,
         "deg":316.012
      },
      "clouds":{
         "all":0
      },
      "weather":[
         {
            "id":800,
            "main":"Clear",
            "description":"Sky is Clear",
            "icon":"01n"
         }
      ],
      "dt":1485755383
   },
   {
      "main":{
         "temp":263.64,
         "pressure":1015,
         "humidity":57,
         "temp_min":262.15,
         "temp_max":265.15
      },
      "wind":{
         "speed":2.6,
         "deg":280
      },
      "clouds":{
         "all":1
      },
      "weather":[
         {
            "id":800,
            "main":"Clear",
            "description":"sky is clear",
            "icon":"01n"
         }
      ],
      "dt":1485780512
   }
   ]
}

History Bulk

We have recently announced the History Bulk functionality that allows to extract historical data per city for 40 years in the past. The price is highly competitive - only 10$ per location!

For accessing this feature please click the next link. The detailed documentation can be found here.

Weather parameters in API response for hourly historical data for cities

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.

List of all API parameters with units openweathermap.org/weather-data

JSON

Example of API response 
                     
{
   "message": "Count: 24",
   "cod": "200",
   "city_id": 4298960,
   "calctime": 0.00297316,
   "cnt": 24,
   "list": [
   {
   "dt": 1578384000,
   "main": {
     "temp": 275.45,
     "feels_like": 271.7,
     "pressure": 1014,
     "humidity": 74,
     "temp_min": 274.26,
     "temp_max": 276.48
   },
   "wind": {
     "speed": 2.16,
     "deg": 87
   },
   "clouds": {
     "all": 90
   },
   "weather": [
     {
       "id": 501,
       "main": "Rain",
       "description": "moderate rain",
       "icon": "10n"
     }
   ],
   "rain": {
     "1h": 0.9
   }
},
....

Fields in API Response

  • message Internal parameter
  • cod Internal parameter
  • city_id City ID
  • calctime Internal parameter
  • 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 (on the sea level, if there is no sea_level or grnd_level data), 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
      • main.sea_level Atmospheric pressure on the sea level, hPa
      • main.grnd_level Atmospheric pressure on the ground level, hPa
    • 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
      • rain.3h Rain volume for the last 3 hours
    • snow
      • snow.1h Snow volume for the last 1 hour
      • snow.3h Snow volume for the last 3 hours
    • weather (more info Weather condition codes)
      • weather.id Weather condition id
      • weather.main Group of weather parameters (Rain, Snow, Extreme etc.)
      • weather.description Weather condition within the group
      • 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 including extreme conditions like tornado, hurricane etc.)

Min/max temperature in historical weather API and forecast API

Please, do not confuse min/max parameters in hourly historical weather API and forecast API. In hourly historical weather API temp_min and temp_max are optional parameters mean min / max temperature in the city at the moment of calculation to show deviation from the average temperature just for your reference. For large cities and megalopolises geographically expanded it might be applicable. In most cases both temp_min and temp_max parameters have the same volume as 'temp'. Please, use temp_min and temp_max parameters optionally.
Example of historical weather for cities API response 
                     
"main":{
   "temp":306.15, // temperature at the moment of calculation
   "pressure":1013,
   "humidity":44,
   "temp_min":306, //min  temperature in the city at the moment of calculation
   "temp_max":306 //max  temperature in the city at the moment of calculation
},

For comparison look at example of daily forecast weather API response

Example of daily forecast weather API response 
                     
"dt":1406080800,
"temp":{
  "day":297.77,  //daily averaged temperature
  "min":293.52, //daily min temperature
  "max":297.77, //daily max temperature
  "night":293.52, //night temperature
  "eve":297.77, //evening temperature
  "morn":297.77, //morning temperature
}