Jay Taylor's notes

back to listing index

Docs | Open-Meteo.com

[web search]
Original source (open-meteo.com)
Tags: api weather weather-forecasting open-data open-meteo.com
Clipped on: 2021-11-19

Weather Forecast API

Select your location, weather variables and start using the API.

Select Coordinates or City

Latitude
Longitude
Select city

Hourly Weather Variables

Temperature (2 m)
Relative Humidity (2 m)
Dewpoint (2 m)
Apparent Temperature
Sealevel Pressure
Precipitation
Weathercode
Snow Depth
Freezinglevel Height
Cloudcover Total
Cloudcover Low
Cloudcover Mid
Cloudcover High
Shortwave Solar Radiation
Direct Solar Radiation
Diffuse Solar Radiation
Direct Normal Irradiance (DNI) New
Evapotranspiration
Vapor Pressure Deficit
Wind Speed (10 m)
Wind Speed (80 m)
Wind Speed (120 m)
Wind Speed (180 m)
Wind Direction (10 m)
Wind Direction (80 m)
Wind Direction (120 m)
Wind Direction (180 m)
Wind Gusts (10 m)
Soil Temperature (0 cm)
Soil Temperature (6 cm)
Soil Temperature (18 cm)
Soil Temperature (54 cm)
Soil Moisture (0-1 cm)
Soil Moisture (1-3 cm)
Soil Moisture (3-9 cm)
Soil Moisture (9-27 cm)
Soil Moisture (27-81 cm)

Daily Weather Variables (*)

Weathercode
Maximum Temperature (2 m)
Minimum Temperature (2 m)
Maximum Apparent Temperature (2 m)
Minimum Apparent Temperature (2 m)
Sunrise
Sunset
Precipitation Sum
Precipitation Hours
Maximum Wind Speed (10 m)
Maximum Wind Gusts (10 m)
Dominant Wind Direction (10 m)
Shortwave Radiation Sum
* Parameter timezone is mandatory

Settings

Current weather with temperature, windspeed and weather code
Temperature Unit
Wind Speed Unit
Precipitation Unit
Timeformat
Timezone
Past days
API URL (Open in new tab)
You can copy this API URL into your application

API Documentation

The API endpoint /v1/forecast accepts a WGS4 coordinate, a list of weather variables and responds with a JSON hourly weather forecast for 7 days. Time always starts at 0:00 today and contains 168 hours. All URL parameters are listed below:

Parameter Format Required Default Description
latitude, longitude Floating point Yes Geographical WGS84 coordiante of the location
hourly String array No A list of weather variables which should be returned. Values can be coma separated, or multiple &hourly= parameter in the URL can be used.
daily String array No A list of daily weather variable aggregations which should be returned. Values can be coma separated, or multiple &daily= parameter in the URL can be used. If daily weather variables are specified, paramter timezone is required.
current_weather Bool No false Include current weather conditions in the JSON output.
temperature_unit String No celsius If fahrenheit is set, all temperature values are converted to Fahrenheit.
windspeed_unit String No kmh Other wind speed speed units: ms, mph and kn
precipitation_unit String No mm Other precipitation amount units: inch
timeformat String No iso8601 If format unixtime is selected, all time values are returned in UNIX epoch time in seconds. Please not that all time is then in UTC! For daily values with unix timestamp, please apply utc_offset_seconds again to get the correct date.
timezone String No UTC If timezone is set, all timestamps are returned as local-time and data is returned starting at 0:00 local-time. Any time zone name from the time zone database is supported.
past_days Integer (0-2) No 0 If past_days is set, yesterdays or the day before yesterdays data are also returned.

Additional optional URL parameters will be added. For API stability, no required parameters will be added in the future!

Hourly Parameter Definition

The parameter &hourly= accepts the following values. Most weather variables are given as an instantaneous value for the indicated hour. Some variables like precipitation are calculated from the preceding hour as and average or sum.

Variable Valid time Unit Description
temperature_2m Instant °C (°F) Air temperature at 2 meters above ground
relativehumidity_2m Instant % Relative humidity at 2 meters above ground
dewpoint_2m Instant °C (°F) Dew point temperature at 2 meters above ground
apparent_temperature Instant °C (°F) Apparent temperature is the perceived feels-like tempertature combinding wind chill factor, realtive humidity and solar radition
pressure_msl Instant hPa Atmospheric air pressure reduced to sea level
cloudcover Instant % Total cloud cover as an area fraction
cloudcover_low Instant % Low level clouds and fog up to 3 km altitude
cloudcover_mid Instant % Mid level clouds from 3 to 8 km altitude
cloudcover_high Instant % High level clouds from 8 km altitude
windspeed_10m
windspeed_80m
windspeed_120m
windspeed_180m		 Instant km/h (mph, m/s, knots) Wind speed at 10, 80, 120 or 180 meters above ground. Wind speed on 10 meters is the standard level.
winddirection_10m
winddirection_80m
winddirection_120m
winddirection_180m		 Instant ° Wind direction at 10, 80, 120 or 180 meters above ground
windgusts_10m Preceding hour max km/h (mph, m/s, knots) Gusts at 10 meters above ground as a maximum of the preceding hour
shortwave_radiation Preceding hour mean W/m² Shortwave solar radiation as average of the preceding hour
direct_radiation
direct_normal_irradiance		 Preceding hour mean W/m² Direct solar radiation as average of the preceding hour on the horizontal plane and the normal plane (perpendicular to the sun)
diffuse_radiation Preceding hour mean W/m² Diffuse solar radiation as average of the preceding hour
vapor_pressure_deficit Instant kPa Vapor Pressure Deificit (VPD) in kilo pascal (kPa). For high VPD (>1.6), water transpiration of plants increases. For low VPD (<0.4), transpiration decreases
evapotranspiration Preceding hour sum mm (inch) Sum of evapotranspration of the preceding hour from lands urface and plants
precipitation Preceding hour sum mm (inch) Total precipitation (rain, showers, snow) sum of the preceding hour
weathercode Instant WMO code Weather condition as a numeric code. Follow WMO weather interpretation codes. See table below for details.
snow_depth Instant meters Snow depth on the ground
freezinglevel_height Instant meters Altitude above sea level of the 0°C level
soil_temperature_0cm
soil_temperature_6cm
soil_temperature_18cm
soil_temperature_54cm		 Instant °C (°F) Temperature in the soil at 0, 6, 18 and 54 cm depths. 0 cm is the surface temperature on land or water surface temperature on water.
soil_moisture_0_1cm
soil_moisture_1_3cm
soil_moisture_3_9cm
soil_moisture_9_27cm
soil_moisture_27_81cm		 Instant m³/m³ Average soil water content as volumetric mixing ratio at 0-1, 1-3, 3-9, 9-27 and 27-81 cm depths.

Daily Parameter Definition

Aggregations are a simple 24 hour aggregation from hourly values. The parameter &daily= accepts the following values:

Variable Unit Description
temperature_2m_max
temperature_2m_min		 °C (°F) Maximum and minimum daily air temperature at 2 meters above ground
apparent_temperature_max
apparent_temperature_min		 °C (°F) Maximum and minimum dailt apparent temperature
precipitation_sum mm Sum of daily precipitation
precipitation_hours hours The number of hours with rain
weathercode WMO code The most severe weather condition on a given day
sunrise
sunset		 iso8601 Sun rise and set times
windspeed_10m_max
windgusts_10m_max		 km/h (mph, m/s, knots) Maximum wind speed and gusts on a day
winddirection_10m_dominant ° Dominant wind direction
shortwave_radiation_sum MJ/m² The sum of solar radiaion on a given day in Mega Joules

JSON Return Object

On success a JSON object will be returned.


{
  "latitude": 52.52,
  "longitude": 13.419,
  "elevation": 44.812,
  "generationtime_ms": 2.2119,
  "utc_offset_seconds": 0,
  "hourly": {
    "time": ["2021-08-28T00:00", "2021-08-28T01:00", "2021-08-28T02:00", ...],
    "temperature_2m": [13, 12.7, 12.7, 12.5, 12.5, 12.8, 13, 12.9, 13.3, ...]
  },
  "hourly_units": {
    "temperature_2m": "°C"
  },
  "current_weather": {
    "time": "2021-08-28T09:00",
    "temperature": 13.3,
    "weathercode": 3,
    "windspeed": 10.3,
    "winddirection": 262
  }
}
Parameter Format Description
latitude, longitude Floating point WGS84 of the center of the weather grid-cell which was used to generate this forecast. This coordinate might be up to 5 km away.
elevation Floating point The elevation in meters of the selected weather grid-cell. In mountain terrain it might differ from the location you would expect.
generationtime_ms Floating point Generation time of the weather forecast in milli seconds. This is mainly used for performance monitoring and improvements.
utc_offset_seconds Integer Applied timezone offset from the &timezone= parameter.
hourly Object For each selected weather variable, data will be returned as a floating point array. Additionally a time array will be returned with ISO8601 timestamps.
hourly_units Object For each selected weather variable, the unit will be listed here.
daily Object For each selected daily weather variable, data will be returned as a floating point array. Additionally a time array will be returned with ISO8601 timestamps.
daily_units Object For each selected daily weather variable, the unit will be listed here.
current_weather Object Current weather conditions with the attributes: time, temperature, windspeed, winddirection and weathercode

Errors

In case an error occurs, for example a URL parameter is not correctly specified, a JSON error object is returned with a HTTP 400 status code.


{
  "error": true,
  "reason": "Cannot initialize WeatherVariable from invalid String value tempeture_2m for key hourly"
}

Weather variable documentation

WMO Weather interpretation codes (WW)

Code Description
0 Clear sky
1, 2, 3 Mainly clear, partly cloudy, and overcast
45, 48 Fog and depositing rime fog
51, 53, 55 Drizzle: Light, moderate, and dense intensity
56, 57 Freezing Drizzle: Light and dense intensity
61, 63, 65 Rain: Slight, moderate and heavy intensity
66, 67 Freezing Rain: Light and heavy intensity
71, 73, 75 Snow fall: Slight, moderate, and heavy intensity
77 Snow grains
80, 81, 82 Rain showers: Slight, moderate, and violent
85, 86 Snow showers slight and heavy
95 * Thunderstorm: Slight or moderate
96, 99 * Thunderstorm with slight and heavy hail

*) Thunderstorm forecast with hail is only available in Central Europe