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 km². 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 using JavaScript.

const response = await fetch(
	"https://api-test.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}`)

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 using Python.

from httpx import Client

with Client() as client:
    response = client.get(
        url="https://api-test.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}")

Example 3

Retrieving the 2-year return period threshold for the 5° by 5° grid cell that the given coordinates fall into using JavaScript.

const response = await fetch(
	"https://api-test.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`)