Back to data catalog
Flood forecasting based on the Global Flood Awareness System (GloFAS)
OpenAPI Spec
Explore the OpenAPI spec for OpenEPI Flood Forecast API
Git Repository
Explore the source code behind OpenEPI Flood Forecast API
Client Libraries
Explore the client libraries for OpenEPI Flood Forecast API
Documentation
Explore the documentation for OpenEPI Flood Forecast API
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 auxiliary 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.
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 km<
Western, Central and Eastern Africa
Spatial Resolution
5° x 5°
Returns the 2-, 5-, and 20-year return period thresholds either for the cell at the given coordinates or for the cells within the given bounding box
1from openepi_client import GeoLocation, BoundingBox
2from openepi_client.flood import FloodClient
3from openepi_client.flood import AsyncFloodClient
4from datetime import date, timedelta
5
6# sync
7
8# Get the return period thresholds for a given geolocation
9thresholds = FloodClient.get_threshold(geolocation=GeoLocation(lat=-3.422, lon=30.075))
10
11# Get the return period thresholds for a given bounding box
12thresholds = FloodClient.get_threshold(bounding_box=BoundingBox(min_lat=4.764412, min_lon=22.0, max_lat=5.015732, max_lon=23.05))
13
14# async
15
16# Get the return period thresholds for a given geolocation
17thresholds = await AsyncFloodClient.get_threshold(geolocation=GeoLocation(lat=-3.422, lon=30.075))
18
19# Get the return period thresholds for a given bounding box
20thresholds = await AsyncFloodClient.get_threshold(bounding_box=BoundingBox(min_lat=4.764412, min_lon=22.0, max_lat=5.015732, max_lon=23.05))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}1import { FloodClient } from 'openepi-client';
2
3const client = new FloodClient();
4
5client.getThresholds({ lon: 22.260536, lat: 4.882569 }).then((result) => {
6 const { data, error } = result;
7 if (error) {
8 console.error(error);
9 } else {
10 console.log(data);
11 }
12});Returns a detailed forecast of the next 30 days either for the cell at the given coordinates or for the cells within the given bounding box
1from openepi_client import GeoLocation, BoundingBox
2from openepi_client.flood import FloodClient
3from openepi_client.flood import AsyncFloodClient
4from datetime import date, timedelta
5
6# sync
7
8# Get a detailed flood forecast for a given coordinate
9detailed = FloodClient.get_detailed(geolocation=GeoLocation(lat=-3.422, lon=30.075))
10
11# Get a detailed flood forecast for a given coordinate and timeframe (inclusive bounds)
12start_date = date.today()
13end_date = start_date + timedelta(days=4)
14detailed = FloodClient.get_detailed(geolocation=GeoLocation(lat=-3.422, lon=30.075), start_date=start_date, end_date=end_date)
15
16# Get a detailed flood forecast for a given bounding box
17detailed = FloodClient.get_detailed(bounding_box=BoundingBox(min_lat=4.764412, min_lon=22.0, max_lat=5.015732, max_lon=23.05))
18
19# async
20
21# Get a detailed flood forecast for a given coordinate
22detailed = await AsyncFloodClient.get_detailed(geolocation=GeoLocation(lat=-3.422, lon=30.075))
23
24# Get a detailed flood forecast for a given coordinate and timeframe (inclusive bounds)
25start_date = date.today()
26end_date = start_date + timedelta(days=4)
27detailed = await AsyncFloodClient.get_detailed(geolocation=GeoLocation(lat=-3.422, lon=30.075), start_date=start_date, end_date=end_date)
28
29# Get a detailed flood forecast for a given bounding box
30detailed = await AsyncFloodClient.get_detailed(bounding_box=BoundingBox(min_lat=4.764412, min_lon=22.0, max_lat=5.015732, max_lon=23.05))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}1import { FloodClient } from 'openepi-client';
2
3const client = new FloodClient();
4
5client.getDetailedForecast({ lon: 22.260536, lat: 4.882569 }).then((result) => {
6 const { data, error } = result;
7 if (error) {
8 console.error(error);
9 } else {
10 console.log(data);
11 }
12});Returns a summary forecast of the next 30 days either for the cell at the given coordinates or for the cells within the given bounding box
1from openepi_client import GeoLocation, BoundingBox
2from openepi_client.flood import FloodClient
3from openepi_client.flood import AsyncFloodClient
4from datetime import date, timedelta
5
6# sync
7
8# Get a summary flood forecast for a given coordinate
9summary = FloodClient.get_summary(geolocation=GeoLocation(lat=-3.422, lon=30.075))
10
11# Get a summary flood forecast for a given coordinate and include neighboring cells
12summary = FloodClient.get_summary(geolocation=GeoLocation(lat=-3.422, lon=30.075), include_neighbors=True)
13
14# Get a summary flood forecast for a given bounding box
15summary = FloodClient.get_summary(bounding_box=BoundingBox(min_lat=4.764412, min_lon=22.0, max_lat=5.015732, max_lon=23.05))
16
17# async
18
19# Get a summary flood forecast for a given coordinate
20summary = await AsyncFloodClient.get_summary(geolocation=GeoLocation(lat=-3.422, lon=30.075))
21
22# Get a summary flood forecast for a given coordinate and include neighboring cells
23summary = await AsyncFloodClient.get_summary(geolocation=GeoLocation(lat=-3.422, lon=30.075), include_neighbors=True)
24
25# Get a summary flood forecast for a given bounding box
26summary = await AsyncFloodClient.get_summary(bounding_box=BoundingBox(min_lat=4.764412, min_lon=22.0, max_lat=5.015732, max_lon=23.05))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}1import { FloodClient } from 'openepi-client';
2
3const client = new FloodClient();
4
5client.getSummaryForecast({ lon: 22.260536, lat: 4.882569 }).then((result) => {
6 const { data, error } = result;
7 if (error) {
8 console.error(error);
9 } else {
10 console.log(data);
11 }
12});