Back to data catalog
Flood API
Flood forecasting based on the Global Flood Awareness System (GloFAS)
OpenAPI Spec
Specification of all endpoints available in the flood api.
Github
Explore the source code behind the flood api.
More info
Data sources
Part of the data for this Flood API consists of the 30-day forecasted river discharge data retrieved on a daily basis from the Copernicus Climate Data Store (CDS). Upstream area data was retrieved from the auxilairy data page of the Copernicus Emergency Management Service (CEMS). Additionally, return period threshold data was obtained directly from the GloFAS team, but this will soon be made available through the CDS as well. All the data is on a global scale with resolution 5° by 5°. Please note that these datasets are licensed under the CEMS-FLOODS datasets licence, which is not a standard open license. We use them in our pre-project to explore relevant data.
Processing
The forecasted river discharge data is processed in order to obtain the summary and detailed forecasts. The summary forecast corresponds to the GloFAS Reporting Point structure, which defines a flood's intensity, tendency, and peak timing over the 30-day forecast horizon for each grid cell. In GloFAS, each reporting point is associated with a discharge hydrograph, which makes up the detailed forecast provided by the API. The detailed forecast provides, for each day of the forecast horizon, values such as the five-number summary of the discharge distribution, as well as the probabilities of exceeding the 2-, 5-, and 20-year return period thresholds.
In our processing pipeline, we first determine the detailed forecast by computing simple statistics at each day of the forecasted discharge data, making use of the GloFAS return period threshold data. Then, we compute the summary forecast by aggregating the detailed forecast data over the forecast horizon. Similarly to GloFAS, the upstream area data is used to filter out grid cells that have an upstream area smaller than 250 km2. Currently, the region of interest is limited to the following bounding box covering parts of Western, Central, and Eastern Africa: -18.0° to 52.0° longitude and -6.0° to 17.0° latitude.
Examples
Example 1
Retrieving the peak day of the summary forecast for the 5° by 5° grid cell that the given coordinates fall into.
1import io.openepi.flood.api.FloodApi;
2import io.openepi.flood.model.SummaryResponseModel;
3import io.openepi.common.ApiException;
4import java.math.BigDecimal;
5import java.time.LocalDate;
6
7public class Main {
8 public static void main(String[] args) {
9 FloodApi api = new FloodApi();
10 try {
11 BigDecimal lon = new BigDecimal("33.57");
12 BigDecimal lat = BigDecimal.valueOf(-1.37);
13 SummaryResponseModel response = api.summarySummaryGetSinglePoint(lon, lat, false);
14
15 // Assumes flood data on this location.
16 LocalDate peakDay = response.getQueriedLocation().getFeatures().get(0).getProperties().getPeakDay();
17 System.out.println("Forecasted peak day: " + peakDay);
18 } catch (ApiException e) {
19 System.err.println("Exception when calling FloodApi#summarySummaryGetSinglePoint");
20 e.printStackTrace();
21 }
22 }
23}
1const response = await fetch(
2 "https://api.openepi.io/flood/summary?" +
3 new URLSearchParams({
4 lon: "33.575897",
5 lat: "-1.375532",
6 })
7)
8const json = await response.json()
9
10// Get the forecasted peak day
11const peakDay = json.queried_location.features[0].properties.peak_day
12
13console.log(`Forecasted peak day: ${peakDay}`)
14
1from httpx import Client
2
3with Client() as client:
4 response = client.get(
5 url="https://api.openepi.io/flood/summary",
6 params={"lon": 33.575897, "lat": -1.375532},
7 )
8
9 # Get the forecasted peak day
10 json = response.json()
11 peak_day = json["queried_location"]["features"][0]["properties"]["peak_day"]
12
13 print(f"Forecasted peak day: {peak_day}")
14
Example 2
Retrieving the minimum forecasted discharge of the first day of the detailed forecast for the 5° by 5° grid cell that the given coordinates fall into.
1import io.openepi.flood.api.FloodApi;
2import io.openepi.flood.model.DetailedResponseModel;
3import io.openepi.common.ApiException;
4import java.math.BigDecimal;
5
6public class Main {
7 public static void main(String[] args) {
8 FloodApi api = new FloodApi();
9 try {
10 BigDecimal lon = new BigDecimal("33.57");
11 BigDecimal lat = BigDecimal.valueOf(-1.37);
12 DetailedResponseModel response = api.detailedDetailedGetSinglePoint(lon, lat, false);
13
14 // Assumes flood data on this location.
15 BigDecimal minDischarge = response.getQueriedLocation().getFeatures().get(0).getProperties().getMinDis();
16 System.out.println("Minimum discharge: " + minDischarge);
17 } catch (ApiException e) {
18 System.err.println("Exception when calling FloodApi#detailedDetailedGetSinglePoint");
19 e.printStackTrace();
20 }
21 }
22}
1const response = await fetch(
2 "https://api.openepi.io/flood/summary?" +
3 new URLSearchParams({
4 lon: "33.575897",
5 lat: "-1.375532",
6 })
7)
8const json = await response.json()
9
10// Get the minimum forecasted discharge
11const minDischarge = json.queried_location.features[0].properties.min_dis
12
13console.log(`Minimum forecasted discharge: ${minDischarge}`)
14
1from httpx import Client
2
3with Client() as client:
4 response = client.get(
5 url="https://api.openepi.io/flood/detailed",
6 params={"lon": 33.575897, "lat": -1.375532},
7 )
8
9 # Get the minimum forecasted discharge
10 json = response.json()
11 peak_day = json["queried_location"]["features"][0]["properties"]["min_dis"]
12
13 print(f"Minimum forecasted discharge: {peak_day}")
14
Example 3
Retrieving the 2-year return period threshold for the 5° by 5° grid cell that the given coordinates fall into.
1import io.openepi.flood.api.FloodApi;
2import io.openepi.common.ApiException;
3import io.openepi.flood.model.ThresholdResponseModel;
4import java.math.BigDecimal;
5
6public class Main {
7 public static void main(String[] args) {
8 FloodApi api = new FloodApi();
9 try {
10 BigDecimal lon = new BigDecimal("33.57");
11 BigDecimal lat = BigDecimal.valueOf(-1.37);
12 ThresholdResponseModel response = api.thresholdThresholdGetSinglePoint(lon, lat);
13
14 // Assumes flood data on this location.
15 BigDecimal threshold2y = response.getQueriedLocation().getFeatures().get(0).getProperties().getThreshold2y();
16 System.out.println("2-year return period threshold in m^3/s: " + threshold2y + " m^3/s");
17 } catch (ApiException e) {
18 System.err.println("Exception when calling FloodApi#thresholdThresholdGetSinglePoint");
19 e.printStackTrace();
20 }
21 }
22}
1const response = await fetch(
2 "https://api.openepi.io/flood/threshold?" +
3 new URLSearchParams({
4 lon: "33.575897",
5 lat: "-1.375532",
6 })
7)
8const json = await response.json()
9
10// Get the 2-year return period threshold
11const threshold2y = json.queried_location.features[0].properties.threshold_2y
12
13console.log(`2-year return period threshold in m^3/s: ${threshold2y} m^3/s`)
14
1from httpx import Client
2
3with Client() as client:
4 response = client.get(
5 url="https://api.openepi.io/flood/threshold",
6 params={"lon": 33.575897, "lat": -1.375532},
7 )
8
9 # Get the 2-year return period threshold
10 json = response.json()
11 threshold_2y = json["queried_location"]["features"][0]["properties"]["threshold_2y"]
12
13 print(f"2-year return period threshold: {threshold_2y} m^3/s")
14