Work in progress!
API Response
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 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 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 | nearest | 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 |
|---|---|---|---|
| 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 | Instant | °C (°F) | Average temperature of the first soil level 0-7 cm below ground. |
| 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. |
| geopotential_height_1000hPa | Instant | gpm | Geopotential height on different atmospheric pressure levels |
| wind_speed_10m | Instant | gpm | 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. |
| relative_humidity_2m relative_humidity_1000hPa, ... | Instant | % | Relative humidity at 2 meters above ground and atmospheric pressure levels |
| specific_humidity_1000hPa, ... | Instant | g/kg | Specific humidity at different atmospheric pressure levels |
| atmosphere_relative_vorticity_1000hPa, ... | Instant | s⁻¹ | Relative vorticity at different atmospheric pressure levels |
| divergence_of_wind, ... | Instant | s⁻¹ | Differgence of wind at different atmospheric pressure levels |
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"