<!-- block-id: concept -->

## Weather History API

### Product concept

We provide hourly historical weather data for any location on the globe via Weather History API. Availability of hourly historical data depends on a type of your [subscription](/price.md#current).

You can also download this data in JSON or CSV format - please read [History Bulk](/history-bulk.md) and [History Forecast Bulk](/api/history-forecast-bulk.md).

<!-- block-id: city -->

## Call hourly historical data

### How to make an API call

```text
https://history.openweathermap.org/data/2.5/history/city?lat={lat}&lon={lon}&type=hour&start={start}&end={end}&appid={API key}
```

### API call

```text
https://history.openweathermap.org/data/2.5/history/city?lat={lat}&lon={lon}&type=hour&start={start}&cnt={cnt}&appid={API key}
```

| Parameters |  |  |
| --- | --- | --- |
| `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) |
| `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) |
| `type` | Yes | Type of the call, keep this parameter in the API call as `hour` |
| `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) |
| `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 the parameter `end`) |

> Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around.
>
> Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality.

### Example of API call

```text
https://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87.65&appid={API key}
```

> 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](/weather-data.md).

<!-- block-id: JSON -->

## JSON

<!-- block-id: fields -->

### Fields in API Response

- `message` Internal parameter
- `cod` Internal parameter
- `city_id`  City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin)
- `calctime` Internal parameter
- `list`  - `dt` Time of data calculation, unix, UTC
  - `main`    - `main.temp` Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. [Learn more](#data)
    - `main.feels_like` This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. [Learn more](#data)
    - `main.pressure` Atmospheric pressure on the sea level, hPa
    - `main.humidity` Humidity, %
    - `main.temp_min` Minimum temperature within a large city or a megalopolis (optional parameter). Please find more [here](#min). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. [Learn more](#data)
    - `main.temp_max` Maximum temperature within a large city or a megalopolis (optional parameter). Please find more [here](#min). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. [Learn more](#data)
    - `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 Default: meter/sec, Metric: meter/sec, Imperial: miles/hour. [Learn more](#data)
    - `wind.deg` Wind direction, degrees (meteorological)
  - `clouds`    - `clouds.all` Cloudiness, %
  - `rain`    - `rain.1h` Rain volume for the last 1 hour, mm. Please note that only mm as units of measurement are available for this parameter
    - `rain.3h` Rain volume for the last 3 hours, mm. Please note that only mm as units of measurement are available for this parameter
  - `snow`    - `snow.1h` Snow volume for the last 1 hour, mm. Please note that only mm as units of measurement are available for this parameter
    - `snow.3h` Snow volume for the last 3 hours, mm. Please note that only mm as units of measurement are available for this parameter
  - `weather` (more info [Weather condition codes](/weather-conditions.md))    - `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](#list)
    - `weather.icon` Weather icon id

<!-- block-id: promotion -->

> We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md)  [Solar Irradiance & Energy Prediction service,](/api.md#solar)  [Road Risk API,](/api/road-risk.md)  [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages.

<!-- block-id: list -->

## List of weather condition codes

List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.)

<!-- block-id: min -->

## 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

```text
"main":{
   "temp":306.15, // temperature at the moment of calculation
   "pressure":1013,
   "humidity":44,
   "temp_min":306.15, //min  temperature in the city at the moment of calculation
   "temp_max":306.15 //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

```text
"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
}
```

<!-- block-id: historybulk -->

## How to get History Bulk functionality

We have recently announced the History Bulk functionality that allows to extract historical data for any location for **47+ years** in the past.

For accessing this feature please click the next [link](https://home.openweathermap.org/history_bulks/new). The detailed documentation can be found [here.](/history-bulk.md)

<!-- block-id: other -->

## Other features

<!-- block-id: geocoding -->

### Geocoding API

Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md).

<!-- block-id: builtin -->

### Built-in geocoding

> Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around.
>
> **Please note that API requests by city name and city id have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.**

<!-- block-id: name -->

### Built-in API request by city name

Call historical data by city name.

### API call

```text
https://history.openweathermap.org/data/2.5/history/city?q={city name},{country code}&type=hour&start={start}&end={end}&appid={API key}
```

### API call

```text
https://history.openweathermap.org/data/2.5/history/city?q={city name},{country code}&type=hour&start={start}&cnt={cnt}&appid={API key}
```

| Parameters |  |  |
| --- | --- | --- |
| `q` | Yes | City name, state code and country code divided by comma, please refer to [ISO 3166](https://www.iso.org/obp/ui/) for the state codes or 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. |
| `type` | Yes | type of the call, keep this parameter in the API call as `hour` |
| `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) |
| `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

```text
https://history.openweathermap.org/data/2.5/history/city?q=London,UK&appid={API key}
```

> 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.

### Example of API response

```text
https://history.openweathermap.org/data/2.5/history/city?q=Munchen,DE&appid={API key}
```

<!-- block-id: cityid -->

### Built-in API request by city ID

Call historical data by city ID.

The list of city IDs can be downloaded [here](https://bulk.openweathermap.org/sample/history.city.list.json.gz).

### API calls

```text
https://history.openweathermap.org/data/2.5/history/city?id={id}&type=hour&start={start}&end={end}&appid={API key}
```

### API call

```text
https://history.openweathermap.org/data/2.5/history/city?id={id}&type=hour&start={start}&cnt={cnt}&appid={API key}
```

| Parameters |  |  |
| --- | --- | --- |
| `id` | Yes | City ID. The list of city IDs 'city.list.json.gz' can be downloaded [here](https://bulk.openweathermap.org/sample/). |
| `type` | Yes | Type of the call, keep this parameter in the API call as `hour` |
| `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) |
| `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

```text
https://history.openweathermap.org/data/2.5/history/city?id=2885679&type=hour&appid={API key}
```

> **Only for Professional and Expert 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.

<!-- block-id: data -->

### Units of measurement

`standard`, `metric`, and `imperial` units are available. [List of all API parameters with available units](/weather-data.md).

| Parameters |  |  |
| --- | --- | --- |
| `units` | optional | `standard`, `metric`, `imperial`. When you do not use the `units` parameter, format is `standard` by default. |

Standard (by default): temperature in Kelvin, wind speed in meter/sec

### Examples of API calls:

```text
https://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87&type=hour&start=1643720400&end=1643806800&appid={API key}
```

Metric: temperature in Celsius, wind speed in meter/sec

### Example of API response

```text
https://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87&type=hour&start=1643720400&end=1643806800&units=metric&appid={API key}
```

Imperial: temperature in Fahrenheit, wind speed in miles/hour

### Example of API response

```text
https://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87&type=hour&start=1643720400&end=1643806800&units=imperial&appid={API key}
```