The API uses open-data ECMWF weather forecasts from the IFS weather model with a resolution of 9
km. However, the open-data access is restricted to a resolution of 25 km and 3-hourly values,
although the model still provides excellent accuracy for large scale weather patterns. For more
detailed local forecasts, we recommend using the generic weather forecast API, which combines weather models up to 1 km resolution seamlessly.
API Response
Data Source
This API uses open-data ECMWF Integrated Forecast System IFS. ECMWF IFS models run every 6 hours at 9 km resolution, but only 0.25° grid spacing (~25 km) is available as open data with a limited number of weather variables at 3-hourly intervals.
AIFS is an artificial intelligence weather model from ECMWF yielding better results as GraphCast and other models. Unfortunately, only 6-hourly time-steps are available. You can find more information about AIFS here. As soon as ECWMF includes additional data, they will be made available in this API.
For hourly and high-resolution data (up to 1 km) try our forecast API which combines multiple models.
| Weather Model | Region | Spatial Resolution | Temporal Resolution | Forecast Length | Update frequency |
|---|---|---|---|---|---|
| IFS | Global | 0.4° (~44 km) | 3-Hourly | 15 days | Every 6 hours |
| IFS | Global | 0.25° (~25 km) | 3-Hourly | 15 days | Every 6 hours |
| AIFS | Global | 0.25° (~28 km) | 6-Hourly | 15 days | Every 6 hours |
API Documentation
The API endpoint /v1/ecmwf accepts a geographical coordinate, a list of weather variables and responds with a JSON hourly weather forecast for 10 days. 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 coordinates of the location. Multiple coordinates can be comma separated. E.g. &latitude=52.52,48.85&longitude=13.41,2.35. To return data for multiple locations the JSON output changes to a list of structures. CSV and XLSX formats add a column location_id. | |
| 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. For multiple locations, elevation can also be comma separated. | |
| 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. |
| wind_speed_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 time is then in GMT+0! For daily values with unix timestamp, please apply utc_offset_seconds again to get the correct date. |
| past_days | Integer (0-92) | No | 0 | If past_days is set, yesterday or the day before yesterday data are also returned. |
| 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 and average or sum.
| Variable | Valid time | Unit | Description |
|---|---|---|---|
| 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. Snowfall amount is not provided by ECMWF directly, instead it is approximated based on total precipitation and temperature |
| precipitation_type | Instantaneous | mm (inch) | 0 = No precipitation, 1 = Rain, 3 = Freezing rain (i.e. supercooled raindrops which freeze on contact with the ground and other surfaces), 5 = Snow, 6 = Wet snow (i.e. snow particles which are starting to melt), 7 = Mixture of rain and snow, 8 = Ice pellets, 12 = Freezing drizzle (i.e. supercooled drizzle which freezes on contact with the ground and other surfaces) |
| runoff | Preceding hour sum | mm (inch) | Execess rain that is not absorbed by the soil |
| weather_code | 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 and snowfall. As ECMWF IFS has barely no information about atmospheric stability, estimation about thunderstorms is not possible. |
| cloud_cover | Instant | % | Total cloud cover as an area fraction. Calculated as a weighted function from low, mid and high level clouds. |
| cloud_cover_low | Instant | % | Low level clouds and fog up to 3 km altitude. In case of ECMWF IFS it is based on relative humidity on pressure levels 1000, 925 and 850 hPa. |
| cloud_cover_mid | Instant | % | Mid level clouds from 3 to 8 km altitude. In case of ECMWF IFS it is based on relative humidity on pressure levels 700 and 500 hPa. |
| cloud_cover_high | Instant | % | High level clouds from 8 km altitude. In case of ECMWF IFS it is based on relative humidity on pressure levels 300, 250 and 200 hPa. |
| pressure_msl surface_pressure | Instant | hPa | Atmospheric air pressure reduced to sea level (Mean sea level) and actual pressure at surface level |
| surface_temperature | Instant | °C (°F) | Temperature of the the surface. Depending on the type of surface (e.g. concrete) this temperature can be significantly higher then the 2 meter air temperature |
| soil_temperature_0_7cm soil_temperature_7_to_28cm soil_temperature_28_to_100cm soil_temperature_100_to_255cm | Instant | °C (°F) | Average temperature of different soil depths below ground. |
| soil_moisture_0_to_7cm soil_moisture_7_to_28cm soil_moisture_28_to_100cm soil_moisture_100_to_255cm | Instant | m³/m³ | Average soil water content as volumetric mixing ratio at 0-7, 7-28, 28-100 and 100-255 cm depths. |
| total_column_integrated_water_vapour | Instant | kg/m² | Total amount of water in the atmosphere. |
| temperature_2m temperature_1000hPa, ... | Instant | °C (°F) | Air temperature 2 meter above ground. Additional temperature in the atmopshere are given on different pressure levels. |
| temperature_2m_min temperature_2m_max | Preceding 3-hour | °C (°F) | Minimum and maximum temperature of the preceding 3 hours. |
| geopotential_height_1000hPa | Instant | meter | Geopotential height on different atmospheric pressure levels |
| wind_speed_10m wind_speed_1000hPa, ... | Instant | km/h (mph, m/s, knots) | Wind speed at 10 meters above ground. Wind speed on 10 meters is the standard level. Additional wind speeds are given on atmospheric pressure levels. |
| wind_direction_10m wind_direction_1000hPa, ... | Instant | ° | Wind direction at 10 meters above ground and different pressure levels. |
| wind_gusts_10m | Preceding 3-hour max | km/h (mph, m/s, knots) | Maximum 3 second wind at 10 m height above ground as a maximum of the preceding 3 hours |
| relative_humidity_1000hPa, ... | Instant | % | Relative humidity at atmospheric pressure levels. Unfortunately, 2 meter relative humidity is unavailable. |
| cloud_cover_1000hPa, ... | Instant | % | Cloud cover at the specified pressure level. Cloud cover is approximated based on relative humidity using Sundqvist et al. (1989) |
| 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). ECMWF IFS open-data does not provide direct and diffuse radiation. 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. Similar to direct radiation, it is approximated based on Razo, Müller Witwer |
| global_tilted_irradiance | Preceding hour mean | W/m² | Total radiation received on a tilted pane as average of the preceding hour. The calculation is assuming a fixed albedo of 20% and in isotropic sky. Please specify tilt and azimuth parameter. Tilt ranges from 0° to 90° and is typically around 45°. Azimuth should be close to 0° (0° south, -90° east, 90° west). If azimuth is set to "nan", the calculation assumes a horizontal tracker. If tilt is set to "nan", it is assumed that the panel has a vertical tracker. If both are set to "nan", a bi-axial tracker is assumed. |
JSON Return Object
On success a JSON object will be returned.
"latitude": 52.52,
"longitude": 13.419,
"generationtime_ms": 2.2119,
"timezone": "Europe/Berlin",
"timezone_abbreviation": "CEST",
"hourly": {
"time": ["2022-07-01T00:00", "2022-07-01T01:00", "2022-07-01T02:00", ...],
"temperature_2m": [13, 12.7, 12.7, 12.5, 12.5, 12.8, 13, 12.9, 13.3, ...]
},
"hourly_units": {
"temperature_2m": "°C"
},
| 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 a few kilometers away from the requested coordinate. |
| generationtime_ms | Floating point | Generation time of the weather forecast in milliseconds. This is mainly used for performance monitoring and improvements. |
| utc_offset_seconds | Integer | Applied timezone offset from the &timezone= parameter. |
| timezone timezone_abbreviation | String | Timezone identifier (e.g. Europe/Berlin) and abbreviation (e.g. CEST) |
| 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. |
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 |
(*) Showers and thunderstorm forecast not available with ECMWF IFS
This service is based on data and products of the European Centre for Medium-Range Weather Forecasts (ECMWF). Source www.ecmwf.int. ECMWF does not accept any liability whatsoever for any error or omission in the data, their availability, or for any loss or damage arising from their use.