<!-- block-id: description -->

## 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](#addlocation). 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](#getlist).
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](#data).

<!-- block-id: addlocation -->

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

```text
http://history.openweathermap.org/data/3.0/history/locations/create?lat={lat}&lon={lon}&appid={API key}
```

| Parameters |  |  |
| --- | --- | --- |
| `lat` | Yes | 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](/api/geocoding-api.md) |
| `lon` | Yes | 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](/api/geocoding-api.md) |
| `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)) |

### Example of API call

```text
http://history.openweathermap.org/data/3.0/history/locations/create?lat=51.8080&lon=-0.1257&appid={API key}
```

```json
{
    "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](/api/history-api-full-archive.md#getlist) below.
> - Historical data will not be recalculated after the first calculation.

<!-- block-id: getlist -->

## 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](#addlocation)), 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

```text
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](#data) of the current document to learn more. |
| `failed` | Internal error. Please contact our [support team](mailto:info@openweathermap.org). |

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

## 3. How to get historical data for added location

### API call

```text
http://history.openweathermap.org/data/3.0/history/result?id={location_id}&start={start_date}&end={end_date}&appid={API key}
```

| Parameters |  |  |
| --- | --- | --- |
| `location_id` | Yes | Location ID, which you received when adding your unique location (please see [section 1](#addlocation) of this documentation) |
| `start_date` | Yes | Any date from 1 January 1979 till 23:59 of the previous day, Unix, UTC |
| `end_date` | Yes | Any date from 1 January 1979 till 23:59 of the previous day, Unix, UTC |
| `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)) |

> 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

```json
{ 
    "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) |

<!-- block-id: response -->

## 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-conditions.md#Weather-Condition-Codes-2))    - `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.)