5 day weather forecast

5 day forecast is available at any location or city. It includes weather data every 3 hours. Forecast is available in JSON or XML format.

Call 5 day / 3 hour forecast data

Please remember that all Examples of API calls that listed on this page are just samples and do not have any connection to the real API service!

By city name

Description:
You can search weather forecast for 5 days with data every 3 hours by city name. All weather data can be obtained in JSON and XML formats.

There is a possibility to receive a central district of the city/town with its own parameters (geographic coordinates/id/name) in API response. Example

API call:
api.openweathermap.org/data/2.5/forecast?q={city name},{country code}
Parameters:

q city name and country code divided by comma, use ISO 3166 country codes

Examples of API calls:
api.openweathermap.org/data/2.5/forecast?q=London,us&mode=xml

By city ID

Description:

You can search weather forecast for 5 days with data every 3 hours by city ID. API responds with exact result. All weather data can be obtained in JSON and XML formats.

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

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

API call:
api.openweathermap.org/data/2.5/forecast?id={city ID}
Parameters:
id city ID
Examples of API calls:
api.openweathermap.org/data/2.5/forecast?id=524901

By geographic coordinates

Description:
You can search weather forecast for 5 days with data every 3 hours by geographic coordinates. All weather data can be obtained in JSON and XML formats.
API call:
api.openweathermap.org/data/2.5/forecast?lat={lat}&lon={lon}
Parameters:
lat, lon coordinates of the location of your interest
Examples of API calls:
api.openweathermap.org/data/2.5/forecast?lat=35&lon=139

By ZIP code

Description:

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

API call:
api.openweathermap.org/data/2.5/forecast?zip={zip code},{country code}
Parameters:

zip zip code

Examples of API calls:

api.openweathermap.org/data/2.5/forecast?zip=94040,us



Bulk downloading

Description:

We provide number of bulk files with current weather and forecasts. More information is on the Bulk page

Bulk downloading is available not for all accounts. To get more information please refer to the price.

Examples of bulk files:

http://bulk.openweathermap.org/sample/


Weather parameters in 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.

JSON

Example of API response:

{"city":{"id":1851632,"name":"Shuzenji",
"coord":{"lon":138.933334,"lat":34.966671},
"country":"JP",
"cod":"200",
"message":0.0045,
"cnt":38,
"list":[{
        "dt":1406106000,
        "main":{
            "temp":298.77,
            "temp_min":298.77,
            "temp_max":298.774,
            "pressure":1005.93,
            "sea_level":1018.18,
            "grnd_level":1005.93,
            "humidity":87,
            "temp_kf":0.26},
        "weather":[{"id":804,"main":"Clouds","description":"overcast clouds","icon":"04d"}],
        "clouds":{"all":88},
        "wind":{"speed":5.71,"deg":229.501},
        "sys":{"pod":"d"},
        "dt_txt":"2014-07-23 09:00:00"}
        ]}
Parameters:
  • code Internal parameter
  • message Internal parameter
  • city
    • city.id City ID
    • city.name City name
    • city.coord
      • city.coord.lat City geo location, latitude
      • city.coord.lon City geo location, longitude
    • city.country Country code (GB, JP etc.)
  • cnt Number of lines returned by this API call
  • list
    • list.dt Time of data forecasted, unix, UTC
    • list.main
      • list.main.temp Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.
      • list.main.temp_min Minimum temperature at the moment of calculation. This is deviation from 'temp' that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.
      • list.main.temp_max Maximum temperature at the moment of calculation. This is deviation from 'temp' that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). 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.weather (more info Weather condition codes)
      • list.weather.id Weather condition id
      • list.weather.main Group of weather parameters (Rain, Snow, Extreme etc.)
      • list.weather.description Weather condition within the group
      • 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.rain
      • list.rain.3h Rain volume for last 3 hours, mm
    • list.snow
      • list.snow.3h Snow volume for last 3 hours
    • list.dt_txt Data/time of calculation, UTC

XML

Example of API repond:

<lastupdate/>
 <calctime>0.6543</calctime>
 <nextupdate/>
</meta>
<sun rise="2015-06-30T10:08:46" set="2015-07-01T01:06:20"/>
<forecast>
 <time from="2015-06-30T09:00:00" to="2015-06-30T12:00:00">
 <symbol number="500" name="light rain" var="10n"/>
 <precipitation value="5" unit="3h" type="rain"/>
 <windDirection deg="253.5" code="WSW" name="West-southwest"/>
 <windSpeed mps="4.9" name="Gentle Breeze"/>
 <temperature unit="celsius" value="16.89" min="16.89" max="17.375"/>
 <pressure unit="hPa" value="989.51"/>
 <humidity value="96" unit="%"/>
 <clouds value="broken clouds" all="64" unit="%"/>
</time>
 <time from="2015-06-30T12:00:00" to="2015-06-30T15:00:00">
 <symbol number="500" name="light rain" var="10d"/>
 <precipitation value="99" unit="3h" type="rain"/>
 <windDirection deg="248.001" code="WSW" name="West-southwest"/>
 <windSpeed mps="4.86" name="Gentle Breeze"/>
 <temperature unit="celsius" value="17.23" min="17.23" max="17.614"/>
 <pressure unit="hPa" value="991.29"/>
 <humidity value="97" unit="%"/>
 <clouds value="scattered clouds" all="44" unit="%"/>
 </time>

...

</forecast>
</weatherdata>
Parameters:
  • location
    • location.name City ID
    • location.type Prototype parameter
    • location.country Country code (GB, JP etc.)
    • location.timezone Prototype parameter
    • location.location
      • location.location.altitude City geo location, altitude above the sea level
      • location.location.latitude City geo location, latitude
      • location.location.longitude City geo location, longitude
      • location.location.geobase Prototype parameter
      • location.location.geobaseid Prototype parameter
  • meta
    • meta.lastupdate Prototype parameter
    • meta.calctime Speed of data calculation
    • meta.nextupdate Prototype 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 3 hours, mm
      • forecast.precipitation.unit Period of measurements. Possilbe value is 1 hour, 3 hours.
      • forecast.precipitation.type Type of precipitation. Possible value is rain, snow.
    • forecast.windDirection
      • forecast.windDirection.deg Wind direction, degrees (meteorological)
      • forecast.windDirection.code Code of the wind direction. Possilbe 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.name Type of the wind
    • forecast.temperature
      • forecast.temperature.unit Unit of measurements. Possilbe valure is Celsius, Kelvin, Fahrenheit.
      • forecast.temperature.value Temperature
      • forecast.temperature.min Minimum temperature at the moment of calculation. This is deviation from 'temp' that is possible for large cities and megalopolises geographically expanded (use these parameter optionally).
      • forecast.temperature.max Maximum temperature at the moment of calculation. This is deviation from 'temp' that is possible for large cities and megalopolises geographically expanded (use these parameter optionally).
    • forecast.pressure
      • forecast.pressure.unit hPa
      • forecast.pressure.value Pressure value
    • forecast.humidity
      • forecast.humidity.unit %
      • forecast.humidity.value Humidity value
    • forecast.clouds
      • forecast.pressure.value Name of the cloudiness
      • forecast.pressure.all Cloudiness
      • forecast.pressure.unit %

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 current weather API and forecast API

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

  • In 5 day / 3 hour forecast API, Hourly forecast API and Current weather API - temp_min and temp_max are optional parameters mean min / max temperature in the city at the current moment to see deviation from current temp 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 - min and max mean maximum and minimum temperature in the day.

Example of current weather API response:
"main":{
"temp":306.15, //current temperature 
"pressure":1013,
"humidity":44,
"temp_min":306, //min current temperature in the city
"temp_max":306 //max current temperature in the city
},
For comparison look at 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

Other features

Format

Description:

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

Parameters:
mode - possible values are JSON and xml. If mode parameter is empty the format is JSON by default.
Examples of API calls:

JSON api.openweathermap.org/data/2.5/weather?q=London

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

Limitation of result

Description:

To limit number of listed cities please setup 'cnt' parameter that specifies the number of lines returned.

Parameters:
cnt number of lines in response
Examples of API calls:

cnt=3 api.openweathermap.org/data/2.5/find?lat=57&lon=-2.15&cnt=3

Units format

Description:

Standard, metric, and imperial units are available.

Parameters:

units metric, imperial. When you do not use units parameter, format is Standard by default.

Temperature is available in Fahrenheit, Celsius and Kelvin units.

  • For temperature in Fahrenheit use units=imperial
  • For temperature in Celsius use units=metric
  • Temperature in Kelvin is used by default, no need to use units parameter in API call

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

Examples of API calls:

standard api.openweathermap.org/data/2.5/find?q=London

metric api.openweathermap.org/data/2.5/find?q=London&units=metric

imperial api.openweathermap.org/data/2.5/find?q=London&units=imperial

Multilingual support

Description:

You can use lang parameter to get the output in your language. We support the following languages that you can use with the corresponded lang values:
Arabic - ar, Bulgarian - bg, Catalan - ca, Czech - cz, German - de, Greek - el, English - en, Persian (Farsi) - fa, Finnish - fi, French - fr, Galician - gl, Croatian - hr, Hungarian - hu, Italian - it, Japanese - ja, Korean - kr, Latvian - la, Lithuanian - lt, Macedonian - mk, Dutch - nl, Polish - pl, Portuguese - pt, Romanian - ro, Russian - ru, Swedish - se, Slovak - sk, Slovenian - sl, Spanish - es, Turkish - tr, Ukrainian - ua, Vietnamese - vi, Chinese Simplified - zh_cn, Chinese Traditional - zh_tw.

NOTE: Translation is only applied for the "description" field.

API call:
http://api.openweathermap.org/data/2.5/forecast?id=524901&lang={lang}
Parameters:
lang language code
Examples of API calls:
http://api.openweathermap.org/data/2.5/forecast?id=524901&lang=zh_cn

Call back function for JavaScript code

Description:

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

Examples of API calls:
api.openweathermap.org/data/2.5/weather?q=London,uk&callback=test