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.
const response = await fetch(
"https://api.openepi.io/flood/summary?" +
new URLSearchParams({
lon: "33.575897",
lat: "-1.375532",
})
)
const json = await response.json()
// Get the forecasted peak day
const peakDay = json.queried_location.features[0].properties.peak_day
console.log(`Forecasted peak day: ${peakDay}`)
from httpx import Client
with Client() as client:
response = client.get(
url="https://api.openepi.io/flood/summary",
params={"lon": 33.575897, "lat": -1.375532},
)
# Get the forecasted peak day
json = response.json()
peak_day = json["queried_location"]["features"][0]["properties"]["peak_day"]
print(f"Forecasted peak day: {peak_day}")
import io.openepi.flood.api.FloodApi;
import io.openepi.flood.model.SummaryResponseModel;
import io.openepi.common.ApiException;
import java.math.BigDecimal;
import java.time.LocalDate;
public class Main {
public static void main(String[] args) {
FloodApi api = new FloodApi();
try {
BigDecimal lon = new BigDecimal("33.57");
BigDecimal lat = BigDecimal.valueOf(-1.37);
SummaryResponseModel response = api.summarySummaryGetSinglePoint(lon, lat, false);
// Assumes flood data on this location.
LocalDate peakDay = response.getQueriedLocation().getFeatures().get(0).getProperties().getPeakDay();
System.out.println("Forecasted peak day: " + peakDay);
} catch (ApiException e) {
System.err.println("Exception when calling FloodApi#summarySummaryGetSinglePoint");
e.printStackTrace();
}
}
}
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.
const response = await fetch(
"https://api.openepi.io/flood/summary?" +
new URLSearchParams({
lon: "33.575897",
lat: "-1.375532",
})
)
const json = await response.json()
// Get the minimum forecasted discharge
const minDischarge = json.queried_location.features[0].properties.min_dis
console.log(`Minimum forecasted discharge: ${minDischarge}`)
from httpx import Client
with Client() as client:
response = client.get(
url="https://api.openepi.io/flood/detailed",
params={"lon": 33.575897, "lat": -1.375532},
)
# Get the minimum forecasted discharge
json = response.json()
peak_day = json["queried_location"]["features"][0]["properties"]["min_dis"]
print(f"Minimum forecasted discharge: {peak_day}")
import io.openepi.flood.api.FloodApi;
import io.openepi.flood.model.DetailedResponseModel;
import io.openepi.common.ApiException;
import java.math.BigDecimal;
public class Main {
public static void main(String[] args) {
FloodApi api = new FloodApi();
try {
BigDecimal lon = new BigDecimal("33.57");
BigDecimal lat = BigDecimal.valueOf(-1.37);
DetailedResponseModel response = api.detailedDetailedGetSinglePoint(lon, lat, false);
// Assumes flood data on this location.
BigDecimal minDischarge = response.getQueriedLocation().getFeatures().get(0).getProperties().getMinDis();
System.out.println("Minimum discharge: " + minDischarge);
} catch (ApiException e) {
System.err.println("Exception when calling FloodApi#detailedDetailedGetSinglePoint");
e.printStackTrace();
}
}
}
Example 3
Retrieving the 2-year return period threshold for the 5° by 5° grid cell that the given coordinates fall into.
const response = await fetch(
"https://api.openepi.io/flood/threshold?" +
new URLSearchParams({
lon: "33.575897",
lat: "-1.375532",
})
)
const json = await response.json()
// Get the 2-year return period threshold
const threshold2y = json.queried_location.features[0].properties.threshold_2y
console.log(`2-year return period threshold in m^3/s: ${threshold2y} m^3/s`)
from httpx import Client
with Client() as client:
response = client.get(
url="https://api.openepi.io/flood/threshold",
params={"lon": 33.575897, "lat": -1.375532},
)
# Get the 2-year return period threshold
json = response.json()
threshold_2y = json["queried_location"]["features"][0]["properties"]["threshold_2y"]
print(f"2-year return period threshold: {threshold_2y} m^3/s")
import io.openepi.flood.api.FloodApi;
import io.openepi.common.ApiException;
import io.openepi.flood.model.ThresholdResponseModel;
import java.math.BigDecimal;
public class Main {
public static void main(String[] args) {
FloodApi api = new FloodApi();
try {
BigDecimal lon = new BigDecimal("33.57");
BigDecimal lat = BigDecimal.valueOf(-1.37);
ThresholdResponseModel response = api.thresholdThresholdGetSinglePoint(lon, lat);
// Assumes flood data on this location.
BigDecimal threshold2y = response.getQueriedLocation().getFeatures().get(0).getProperties().getThreshold2y();
System.out.println("2-year return period threshold in m^3/s: " + threshold2y + " m^3/s");
} catch (ApiException e) {
System.err.println("Exception when calling FloodApi#thresholdThresholdGetSinglePoint");
e.printStackTrace();
}
}
}