Preview and API URL
Data Source
Ensemble models are a type of weather forecasting technique that use multiple members or versions of a model to produce a range of possible outcomes for a given forecast. Each member is initialized with slightly different initial conditions and/or model parameters to account for uncertainties and variations in the atmosphere, resulting in a set of perturbed forecasts.
By combining the perturbed forecasts, the ensemble model generates a probability distribution of possible outcomes, indicating not only the most likely forecast but also the range of possible outcomes and their likelihoods. This probabilistic approach provides more comprehensive and accurate forecast guidance, especially for high-impact weather events where uncertainties are high.
Different national weather services calculate ensemble models, each with varying resolutions of weather variables and forecast time-range. For instance, the German weather service DWD's ICON model provides exceptionally high resolution for Europe but only forecasts up to 7 days. Meanwhile, the GFS model can forecast up to 35 days, albeit at a lower resolution of 50 km. The appropriate ensemble model to use would depend on the forecast horizon and region of interest.
| National Weather Service | Weather Model | Region | Resolution | Members | Forecast Length | Update frequency |
|---|---|---|---|---|---|---|
| Deutscher Wetterdienst (DWD) | ICON-D2-EPS | Central Europe | 2 km, hourly | 20 | 2 days | Every 3 hours |
| ICON-EU-EPS | Europe | 13 km, hourly | 40 | 5 days | Every 6 hours | |
| ICON-EPS | Global | 26 km, hourly | 40 | 7.5 days | Every 12 hours | |
| NOAA | GFS Ensemble 0.25° | Global | 25 km, 3-hourly | 31 | 10 days | Every 6 hours |
| GFS Ensemble 0.5° | Global | 50 km, 3-hourly | 31 | 35 days | Every 6 hours | |
| ECMWF | IFS | Global | 44 km, 3-hourly | 51 | 10 days | Every 6 hours |
| Canadian Weather Service | GEM | Global | 2.5 km, 3-hourly | 21 | 16 days (32 days every thursday) | Every 12 hours |
To ensure ease of use, all data is interpolated to a 1-hourly time-step resolution. As the forecast horizon extends further into the future, some ensemble models may reduce the time resolution to 6-hourly intervals.
API Documentation
The API endpoint /v1/ensemble accepts a geographical coordinate, a list of weather variables and responds with a JSON hourly weather forecast for 7 days for each ensemble member. Time always starts at 0:00 today. All URL parameters are listed below:
| Parameter | Format | Required | Default | Description |
|---|---|---|---|---|
| latitude, longitude | Floating point | Yes | Geographical WGS84 coordinate of the location | |
| models | String array | Yes | Select one or more ensemble weather models as comma-separated list | |
| elevation | Floating point | No | The elevation used for statistical downscaling. Per default, a 90 meter digital elevation model is used. You can manually set the elevation to correctly match mountain peaks. If &elevation=nan is specified, downscaling will be disabled and the API uses the average grid-cell height. | |
| hourly | String array | No | A list of weather variables which should be returned. Values can be comma separated, or multiple &hourly= parameter in the URL can be used. | |
| 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 note that all timestamp are in GMT+0! For daily values with unix timestamps, please apply utc_offset_seconds again to get the correct date. |
| timezone | String | No | GMT | If timezone is set, all timestamps are returned as local-time and data is returned starting at 00:00 local-time. Any time zone name from the time zone database is supported. If auto is set as a time zone, the coordinates will be automatically resolved to the local time zone. |
| past_days | Integer | No | 0 | If past_days is set, past weather data can be returned. |
| forecast_days | Integer (0-16) | No | 7 | Per default, only 7 days are returned. Up to 16 days of forecast are possible. |
| start_date end_date | String (yyyy-mm-dd) | No | The time interval to get weather data. A day must be specified as an ISO8601 date (e.g. 2022-06-30). | |
| cell_selection | String | No | land | Set a preference how grid-cells are selected. The default land finds a suitable grid-cell on land with similar elevation to the requested coordinates using a 90-meter digital elevation model. sea prefers grid-cells on sea. nearest selects the nearest possible grid-cell. |
| apikey | String | No | Only required to commercial use to access reserved API resources for customers. The server URL requires the prefix customer-. See pricing for more information. |
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 an 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 temperature combining wind chill factor, relative humidity and solar radiation |
| pressure_msl surface_pressure | Instant | hPa | Atmospheric air pressure reduced to mean sea level (msl) or pressure at surface. Typically pressure on mean sea level is used in meteorology. Surface pressure gets lower with increasing elevation. |
| cloudcover | Instant | % | Total cloud cover as an area fraction |
| windspeed_10m windspeed_80m windspeed_120m | Instant | km/h (mph, m/s, knots) | Wind speed at 10, 80 or 120 meters above ground. Wind speed on 10 meters is the standard level. |
| winddirection_10m winddirection_80m winddirection_120m | Instant | ° | Wind direction at 10, 80 or 120 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. This is equal to the total global horizontal irradiation |
| 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). HRRR offers direct radiation directly. In GFS it is approximated based on Razo, Müller Witwer |
| diffuse_radiation | Preceding hour mean | W/m² | Diffuse solar radiation as average of the preceding hour. HRRR offers diffuse radiation directly. In GFS it is approximated based on Razo, Müller Witwer |
| vapor_pressure_deficit | Instant | kPa | Vapor Pressure Deificit (VPD) in kilopascal (kPa). For high VPD (>1.6), water transpiration of plants increases. For low VPD (<0.4), transpiration decreases |
| evapotranspiration | Preceding hour sum | mm (inch) | Evapotranspration from land surface and plants that weather models assumes for this location. Available soil water is considered. 1 mm evapotranspiration per hour equals 1 liter of water per spare meter. |
| et0_fao_evapotranspiration | Preceding hour sum | mm (inch) | ET₀ Reference Evapotranspiration of a well watered grass field. Based on FAO-56 Penman-Monteith equations ET₀ is calculated from temperature, wind speed, humidity and solar radiation. Unlimited soil water is assumed. ET₀ is commonly used to estimate the required irrigation for plants. |
| weathercode | Instant | WMO code | Weather condition as a numeric code. Follow WMO weather interpretation codes. See table below for details. Weather code is calculated from cloud cover analysis, precipitation, snowfall, cape, lifted index and gusts. |
| precipitation | Preceding hour sum | mm (inch) | Total precipitation (rain, showers, snow) sum of the preceding hour |
| snowfall | Preceding hour sum | cm (inch) | Snowfall amount of the preceding hour in centimeters. For the water equivalent in millimeter, divide by 7. E.g. 7 cm snow = 10 mm precipitation water equivalent |
| rain | Preceding hour sum | mm (inch) | Liquid precipitation of the preceding hour in millimeter |
| 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 |
| visibility | Instant | meters | Viewing distance in meters. Influenced by low clouds, humidity and aerosols. Maximum visibility is approximately 24 km. |
| cape | Instant | J/kg | Convective available potential energy. See Wikipedia. |
| surface_temperature | Instant | °C (°F) | Temperature of the top soil level |
| soil_temperature_0_to_10cm soil_temperature_10_to_40cm soil_temperature_40_to_100cm soil_temperature_100_to_200cm | Instant | °C (°F) | Temperature in the soil as an average on 0-10, 10-40, 40-100 and 100-200 cm depths. |
| soil_moisture_0_to_10cm soil_moisture_10_to_40cm soil_moisture_40_to_100cm soil_moisture_100_to_200cm | Instant | m³/m³ | Average soil water content as volumetric mixing ratio at 0-10, 10-40, 40-100 and 100-200 cm depths. |