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

## Hourly forecast

### Product concept

Hourly forecast for 4 days (96 timestamps). Weather data is available in JSON and XML formats.

<!-- block-id: 5days -->

## Call hourly forecast data

<!-- block-id: geo5 -->

### How to make an API call

You can search weather forecast for 4 days with data every hour by geographic coordinates.

All weather data can be obtained in JSON and XML formats.

### API call

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat={lat}&lon={lon}&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) |
| `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)) |
| `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) |
| `cnt` | optional | A number of timestamps in response. [Learn more](#limit) |
| `lang` | optional | Language code. [Learn more](#multi) |

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

### API call example

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=44.34&lon=10.99&appid={API key}
```

<!-- block-id: parameter -->

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

<!-- block-id: fields_JSON -->

### JSON format API response fields

- `cod` Internal parameter
- `message` Internal parameter
- `cnt` Number of timestamps returned by this API call
- - `list.dt ` Time of data forecasted, Unix, UTC
  - - `list.main.temp` Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit
    - `list.main.feels_like` This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit
    - `list.main.temp_min` Minimum temperature at the moment of calculation. This is minimal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here.](#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit
    - `list.main.temp_max` Maximum temperature at the moment of calculation. This is maximal forecasted temperature (within large megalopolises and urban areas), use these parameter optionally. Please find more info [here.](#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit
    - `list.main.pressure` Atmospheric pressure on the sea level by default, hPa
    - `list.main.sea_level` Atmospheric pressure on the sea level, hPa
    - `list.main.grnd_level` Atmospheric pressure on the ground level, hPa
    - `list.main.humidity` Humidity, %
    - `list.main.temp_kf` Internal parameter
    - `list.main.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit
  - `list.weather`    - `list.weather.id` Weather condition id
    - `list.weather.main` Group of weather parameters (Rain, Snow, Clouds etc.)
    - `list.weather.description` Weather condition within the group. Please find more [here.](#list) You can get the output in your language. [Learn more](#multi)
    - `list.weather.icon` Weather icon id
  - `list.clouds`    - `list.clouds.all` Cloudiness, %
  - `list.wind`    - `list.wind.speed` Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour
    - `list.wind.deg` Wind direction, degrees (meteorological)
    - `list.wind.gust` Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour
  - `list.rain`    - `list.rain.1h` Rain volume for last hour, mm. Please note that only mm as units of measurement are available for this parameter
  - `list.snow`    - `list.snow.1h`Snow volume (water equivalent) for last hour, mm Please note that only mm as units of measurement are available for this parameter
  - `list.visibility` Average visibility, metres. The maximum value of the visibility is 10km
  - `list.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100%
  - `list.sys`    - `list.sys.pod` Part of the day (n - night, d - day)
  - `list.dt_txt` Time of data forecasted, ISO, UTC
  - `city`    - `city.id`  City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin)
    - `city.name`  City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin)
    - `city.coord`      - `city.coord.lat ` Geo location, latitude
      - `city.coord.lon` Geo location, longitude
  - `country`Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin)
  - `timezone` Shift in seconds from UTC
  - `sunrise` Sunrise time, Unix, UTC
  - `sunset` Sunset time, Unix, UTC

<!-- block-id: fields_XML -->

### XML format API response fields

- `location`  - `location.name `  City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin)
  - `location.type` Internal parameter
  - `location.country`  Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin)
  - `location.timezone` Shift in seconds from UTC
  - `location.location`    - `location.location.altitude` Geo location, altitude above the sea level
    - `location.location.latitude` Geo location, latitude
    - `location.location.longitude` Geo location, longitude
    - `location.location.geobase` Internal parameter
    - `location.location.geobaseid` Internal parameter
- `credit` Internal parameter
- `meta`  - `meta.lastupdate` Internal parameter
  - `meta.calctime` Speed of data calculation
  - `meta.nextupdate` Internal parameter
- `sun`  - `sun.rise` Sunrise time
  - `sun.set` Sunset time
- `forecast`  - `forecast.time`    - `forecast.time.from` Beginning of the period of data forecasted
    - `forecast.time.to` End of the period of data forecasted
  - `forecast.symbol`    - `forecast.symbol.number` Weather condition id
    - `forecast.symbol.name` Weather condition
    - `forecast.symbol.var` Weather icon id
  - `forecast.precipitation`    - `forecast.precipitation.value` Precipitation volume for the last hour, mm. Please note that only mm as units of measurement are available for this parameter
    - `forecast.precipitation.unit` Period of measurements. Possible value is 1 hour
    - `forecast.precipitation.type` Type of precipitation. Possible value is rain, snow
    - `forecast.precipitation.probability` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100%
  - `forecast.windDirection`    - `forecast.windDirection.deg` Wind direction, degrees (meteorological)
    - `forecast.windDirection.code` Code of the wind direction. Possible value is WSW, N, S etc.
    - `forecast.windDirection.name` Full name of the wind direction
  - `forecast.windSpeed`    - `forecast.windSpeed.mps` Wind speed, meters per second
    - `forecast.windSpeed.unit` Unit of measurements
    - `forecast.windSpeed.name` Type of the wind
  - `forecast.windGust`    - `forecast.windGust.gust` Wind gust, meters per second
    - `forecast.windGust.unit` Unit of measurements
  - `forecast.temperature`    - `forecast.temperature.unit` Unit of measurements. Possible value is Celsius, Kelvin, Fahrenheit.
    - `forecast.temperature.value` Temperature
    - `forecast.temperature.min` Minimum temperature at the moment of calculation. This is minimal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here.](#min)
    - `forecast.temperature.max` Maximum temperature at the moment of calculation. This is maximal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here](#min)
  - `forecast.feels_like`    - `forecast.feels_like.unit` Unit of measurements. Possible value is Celsius, Kelvin, Fahrenheit. Unit Default: Kelvin
    - `forecast.feels_like.value` Temperature. This temperature parameter accounts for the human perception of weather
  - `forecast.pressure`    - `forecast.pressure.unit` hPa
    - `forecast.pressure.value` Pressure value
  - `forecast.humidity`    - `forecast.humidity.unit` %
    - `forecast.humidity.value` Humidity value
  - `forecast.clouds`    - `forecast.clouds.value` Name of the cloudiness
    - `forecast.clouds.all` Cloudiness
    - `forecast.clouds.unit` %
  - `forecast.visibility`    - `forecast.visibility.value` Average visibility, metres. The maximum value of the visibility is 10km

<!-- 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 our weather API

Please do not confuse min/max parameters in our weather APIs.

- In **Hourly forecast API**, [Current weather API](/current.md) and [5 day / 3 hour forecast API](/forecast5.md) - **temp_min** and **temp_max** are optional parameters mean min / max temperature in the city at the current moment 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 in current weather API optionally.
- In [16 Day forecast](/forecast16.md) - **min** and **max** mean maximum and minimum temperature in the day.

### Example of current weather API response

```text
"main":{
   "temp":306.15, //current temperature
   "pressure":1013,
   "humidity":44,
   "temp_min":306.15, //min current temperature in the city
   "temp_max":306.15 //max current temperature in the city
   },
```

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: other -->

## Other features

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

### Geocoding AP

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, zip-codes 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: name5 -->

### Built-in API request by city name

You can search weather forecast for 4 days (96 hours) with data every hour by city name. All weather data can be obtained in JSON and XML formats.

### API call

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?q={city name}&appid={API key}
```

### API call

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?q={city name},{country code}&appid={API key}
```

### API call

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?q={city name},{state code},{country code}&appid={API key}
```

| Parameters |  |  |
| --- | --- | --- |
| `q` | Yes | 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. |
| `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)) |
| `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) |
| `cnt` | optional | A number of timestamps in response. [Learn more](#limit) |
| `lang` | optional | Language code. [Learn more](#multi) |

### API call examples

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?q=London,us&mode=xml&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://pro.openweathermap.org/data/2.5/forecast/hourly?q=München,DE&appid={API key}
```

<!-- block-id: cityid5 -->

### Built-in API request by city ID

You can search weather forecast for 4 days with data every hour by city ID.

List of city ID city.list.json.gz can be downloaded here [http://bulk.openweathermap.org/sample/](http://bulk.openweathermap.org/sample/)

We recommend to call API by city ID to get unambiguous result for your city.

### API call

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?id={city ID}&appid={API key}
```

| Parameters |  |  |
| --- | --- | --- |
| `id` | Yes | city ID |
| `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)) |
| `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) |
| `cnt` | optional | A number of timestamps in response. [Learn more](#limit) |
| `lang` | optional | Language code. [Learn more](#multi) |

### API call example

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?id=524901&appid={API key}
```

<!-- block-id: zip -->

### Built-in API request by ZIP code

Please note if country is not specified then the search works for USA as a default.

### API call

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?zip={zip code},{country code}&appid={API key}
```

| Parameters |  |  |
| --- | --- | --- |
| `zip` | Yes | Zip code |
| `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)) |
| `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) |
| `cnt` | optional | A number of timestamps in response. [Learn more](#limit) |
| `lang` | optional | Language code |

### API call example

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?zip=94040,us&appid={API key}
```

<!-- block-id: format -->

### Format

JSON format is used by default. To get data in XML format just set up mode = xml.

| Parameters |  |  |
| --- | --- | --- |
| `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. |

JSON

### API call examples

```text
api.openweathermap.org/data/2.5/weather?q=London&appid={API key}
```

XML

### Example of API response

```text
api.openweathermap.org/data/2.5/weather?q=London&mode=xml
```

<!-- block-id: limit -->

### Limitation of result

To limit number of listed cities please setup `cnt` parameter that specifies the number of timestamps returned.

| Parameters |  |  |
| --- | --- | --- |
| `cnt` | optional | A number of timestamps in response |

cnt=3

### API call example

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15{API key}&cnt=3
```

### API call example

```json
{
  "cod": "200",
  "message": 0,
  "cnt": 3,
  "list": [
    {
      "dt": 1647356400,
      "main": {
        "temp": 281.98,
        "feels_like": 278.65,
        "temp_min": 280.57,
        "temp_max": 281.98,
        "pressure": 1014,
        "sea_level": 1014,
        "grnd_level": 1014,
        "humidity": 81,
        "temp_kf": 1.41,
		"dew_point": 279.01
      },
      "weather": [
        {
          "id": 804,
          "main": "Clouds",
          "description": "overcast clouds",
          "icon": "04d"
        }
      ],
      "clouds": {
        "all": 100
      },
      "wind": {
        "speed": 6.78,
        "deg": 184,
        "gust": 12.14
      },
      "visibility": 10000,
      "pop": 0.34,
      "sys": {
        "pod": "d"
      },
      "dt_txt": "2022-03-15 15:00:00"
    },
    {
      "dt": 1647360000,
      "main": {
        "temp": 281.8,
        "feels_like": 278.45,
        "temp_min": 281.06,
        "temp_max": 281.8,
        "pressure": 1014,
        "sea_level": 1014,
        "grnd_level": 1014,
        "humidity": 79,
        "temp_kf": 0.74,
		"dew_point": 278.36
      },
      "weather": [
        {
          "id": 804,
          "main": "Clouds",
          "description": "overcast clouds",
          "icon": "04d"
        }
      ],
      "clouds": {
        "all": 100
      },
      "wind": {
        "speed": 6.68,
        "deg": 186,
        "gust": 11.8
      },
      "visibility": 10000,
      "pop": 0.28,
      "sys": {
        "pod": "d"
      },
      "dt_txt": "2022-03-15 16:00:00"
    },
    {
      "dt": 1647363600,
      "main": {
        "temp": 281.58,
        "feels_like": 278.29,
        "temp_min": 280.99,
        "temp_max": 281.58,
        "pressure": 1014,
        "sea_level": 1014,
        "grnd_level": 1014,
        "humidity": 79,
        "temp_kf": 0.59,
		"dew_point": 278.22
      },
      "weather": [
        {
          "id": 804,
          "main": "Clouds",
          "description": "overcast clouds",
          "icon": "04d"
        }
      ],
      "clouds": {
        "all": 100
      },
      "wind": {
        "speed": 6.33,
        "deg": 181,
        "gust": 11.26
      },
      "visibility": 10000,
      "pop": 0.24,
      "sys": {
        "pod": "d"
      },
      "dt_txt": "2022-03-15 17:00:00"
    }
  ],
  "city": {
    "id": 2641549,
    "name": "Newtonhill",
    "coord": {
      "lat": 57,
      "lon": -2.15
    },
    "country": "GB",
    "population": 3284,
    "timezone": 0,
    "sunrise": 1647325488,
    "sunset": 1647367827
  }
}
```

<!-- 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 | Units of measurement. `metric`, `imperial`. When you do not use units parameter, format is Standard by default |

> Temperature is available in Fahrenheit, Celsius and Kelvin units.
>
> List of all API parameters with units [openweathermap.org/weather-data](/weather-data.md)

Standard

### API call examples

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&appid={API key}
```

### Example of API response

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&appid={API key}&units=metric
```

### Example of API response

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&appid={API key}&units=imperial
```

<!-- block-id: multi -->

### Multilingual support

You can use `lang` parameter to get the output in your language.  Translation is applied for the `city name` and `description` fields.

### API call

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&appid={API key}&lang={lang}
```

| Parameters |  |  |
| --- | --- | --- |
| `lang` | optional | Language code |

### API call example

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&lang=zh_cn&appid={API key}
```

We support the following languages that you can use with the corresponded lang values:

- `sq` Albanian
- `af` Afrikaans
- `ar` Arabic
- `az` Azerbaijani
- `eu` Basque
- `be` Belarusian
- `bg` Bulgarian
- `ca` Catalan
- `zh_cn` Chinese Simplified
- `zh_tw` Chinese Traditional
- `hr` Croatian
- `cz` Czech
- `da` Danish
- `nl` Dutch
- `en` English
- `fi` Finnish
- `fr` French
- `gl` Galician
- `de` German
- `el` Greek
- `he` Hebrew
- `hi` Hindi
- `hu` Hungarian
- `is` Icelandic
- `id` Indonesian
- `it` Italian
- `ja` Japanese
- `kr` Korean
- `ku` Kurmanji (Kurdish)
- `la` Latvian
- `lt` Lithuanian
- `mk` Macedonian
- `no` Norwegian
- `fa` Persian (Farsi)
- `pl` Polish
- `pt` Portuguese
- `pt_br` Português Brasil
- `ro` Romanian
- `ru` Russian
- `sr` Serbian
- `sk` Slovak
- `sl` Slovenian
- `sp, es` Spanish
- `sv, se` Swedish
- `th` Thai
- `tr` Turkish
- `ua, uk` Ukrainian
- `vi` Vietnamese
- `zu` Zulu

<!-- block-id: call -->

### Call back function for JavaScript code

To use JavaScript code you can transfer `callback` functionName to JSONP callback.

### API call example

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&callback=test&appid={API key}
```