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}

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}

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}