Data Source
This API uses reanalysis and forecast data from the Global Flood Awareness System (GloFAS). Per default, GloFAS version 3 with seamless data from 1984 until 7 months of forecast is used. Data from version 4 have been available since 16. November 2022, but only as historical reanalysis data.
Please note: Due to the 5-10 km resolution the closest river might not be selected correctly. Varying coordiantes by 0.1° can help to get a more representable discharge rate. The GloFAS website provides additional maps to help understand how rivers are covered in this dataset.
| Weather Model | Region | Spatial Resolution | Temporal Resolution | Data Length | Update frequency |
|---|---|---|---|---|---|
| GloFAS v3 Reanalysis | Global | 0.1° (~11 km) | Daily | 1984 - July 2022 | - |
| GloFAS v3 Forecast | Global | 0.1° (~11 km) | Daily | 30 days forecast | Daily |
| GloFAS v3 Seasonal Forecast | Global | 0.1° (~11 km) | Daily | 7 months forecast | Monthly |
| GloFAS v4 Reanalysis | Global | 0.05° (~5 km) | Daily | 1984 - July 2022 | - |
| GloFAS v4 Forecast * | Global | 0.05° (~5 km) | Daily | 30 days forecast | Daily |
| GloFAS v4 Seasonal Forecast * | Global | 0.05° (~5 km) | Daily | 7 months forecast | Monthly |
API Documentation
The API endpoint /v1/flood accepts a geographical coordinate and returns river discharge data from the largest river in a 5 km area for the given coordinates. All URL parameters are listed below:
| Parameter | Format | Required | Default | Description |
|---|---|---|---|---|
| latitude, longitude | Floating point | Yes | Geographical WGS84 coordinate of the location | |
| daily | String array | No | A list of weather variables which should be returned. Values can be comma separated, or multiple &daily= parameter in the URL can be used. | |
| 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! |
| past_days | Integer | No | 0 | If past_days is set, past data can be returned. |
| forecast_days | Integer (0-16) | No | 92 | Per default, only 92 days are returned. Up to 210 days of forecast are possible. |
| start_date end_date |
String (yyyy-mm-dd) | No | The time interval to get data. A day must be specified as an ISO8601 date (e.g. 2022-06-30). Data are available from 1984-01-01 until 7 month forecast. | |
| ensemble | Boolean | No | If True all forecast ensemble members will be returned | |
| 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!
Daily Parameter Definition
The parameter &daily= accepts the following values:
| Variable | Unit | Description |
|---|---|---|
| river_discharge | m³/s | Daily river discharge rate in m³/s |
| river_discharge_mean river_discharge_median river_discharge_max river_discharge_min river_discharge_p25 river_discharge_p75 |
m³/s | Statistical analysis from ensemble members for river discharge rate in m³/s. Only available for forecasts and not for consolidated historical data. |
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. |
| daily | 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. |
| daily_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"