Building Simple Flood Warning Systems with Public APIs — Tethys Summit 2026 Workshops

This resource contains the two hands-on workshop notebooks and the framing presentation delivered at the Tethys Platform Summit (Chicago, IL, June 17–18, 2026). Both notebooks teach how to build a working river flood-warning tool from freely available streamflow APIs, using only Python in Google Colab — no local installation or model setup required.

The two notebooks are independent and use different data services to reach a similar end:

• Workshop 1 — "Will It Flood?" uses the U.S.-focused NOAA NWPS and CIROH NWM APIs.
• Workshop 2 — "GEOGLOWS RFS vs. USGS" uses the global GEOGLOWS streamflow service.

The presentation provides the scientific and operational context for both.

Contents

How to run the notebooks

Both notebooks are written for Google Colab and are meant to be run top to bottom.

1. Open a notebook in Google Colab.
2. Make your own copy (File → Save a copy in Drive) before editing.
3. Run the cells in order (Runtime → Run all, or cell by cell).

Workshop 1 additionally requires a CIROH NWM API key (see Requirements below). Workshop 2 needs no key.

The live Colab links used at the summit: - Workshop 1: https://tinyurl.com/tethys26-wb1 - Workshop 2: https://tinyurl.com/tethys26-wb2

Requirements

Workshop 1 installs and uses: requests, pandas, matplotlib, folium, python-dotenv. It requires a free CIROH NWM API key for the return-period and historical-forecast endpoints. In Colab, store it as a notebook secret named CIROH_API_KEY (key icon in the left sidebar → add CIROH_API_KEY → enable notebook access). Do not commit the key to GitHub or paste it into a cell.

Workshop 2 installs and uses: geoglows, dataretrieval, hydrostats, plotly, pandas, numpy, fsspec. No API key required.

Both notebooks call live web services, so they require an internet connection. The NWPS API occasionally times out; re-running the affected cell usually resolves it.

What each notebook does

Workshop 1 — flood_warning_system_workshop1.ipynb

Given a single NWM river reach ID, the notebook: 1. Pulls reach metadata and nearby USGS gauges from the NOAA NWPS API. 2. Pulls short-, medium-, and long-range streamflow forecasts for that reach from NWPS. 3. Pulls 2- to 100-year return-period flood thresholds from the CIROH NWM API. 4. Plots forecasts against thresholds as color-coded hydrographs. 5. Checks every forecast against every threshold and prints a warning banner (what threshold is crossed, when, and how many ensemble members agree). 6. Maps the reach and nearby USGS gauges with folium.

It ends with 5 challenges (extending the working system to your own reach, live floods, peak flow, total volume, and a historical forecast-vs-observed comparison via the CIROH /forecast endpoint and USGS observed discharge). Each challenge has a TODO cell and a collapsible solution.

Workshop 2 — flood_warning_system_workshop2.ipynb

For a chosen GEOGLOWS River ID (9-digit, from the TDX-Hydro dataset), the notebook: 1. Downloads the GEOGLOWS retrospective simulation (ECMWF ERA5-driven, cms). 2. Downloads USGS observed instantaneous discharge (NWIS, parameter 00060, ft³/s, converted to cms). 3. Aligns the two series and compares them on a hydrograph (plotly). 4. Identifies the peak flood event and computes total flood volume. 5. Builds an Early Warning System: fetches the latest GEOGLOWS forecast and return-period thresholds, draws warning bands (2- through 50-year+), and classifies the flood category.

It includes 4 challenges (your own river, peak flow, flood volume, and a warning graph for a real storm). Each has fill-in (___) cells.

Presentation — continental-scale-forecasts.pptx

A 49-slide keynote, "Forecasting Flow in Every River Everywhere All at Once: Advances in Continental-Scale Hydrologic Modelling and Simulation." It situates the workshops in the broader context of global water security and continental-scale forecasting — covering GloFAS, Google FloodHub, the U.S. National Water Model, and the GEOGLOWS ECMWF Streamflow Service — and uses the 2023 Derna, Libya flood as a case study. The final slides point directly to the two workshop notebooks.

Data sources and units

USGS discharge is converted to cms in Workshop 2 by multiplying by 0.028317.

Unit handling differs between the two notebooks (Workshop 1 reconciles to ft³/s; Workshop 2 works in cms). Read each notebook's data section before reusing values across the two.

Glossary

• API — Application Programming Interface
• CIROH — Cooperative Institute for Research to Operations in Hydrology
• cms — cubic meters per second (m³/s)
• COMID / River ID — Common Identifier for a river reach
• EWS — Early Warning System
• ft³/s (cfs) — cubic feet per second
• GEOGLOWS — GEOGLOWS ECMWF Streamflow Service (global hydrologic forecasting)
• NWM — (U.S.) National Water Model
• NWPS — NOAA National Water Prediction Service
• NWIS — USGS National Water Information System
• RFS — River Forecast System (GEOGLOWS)
• TDX-Hydro — global hydrographic stream network underlying GEOGLOWS River IDs
• USGS — U.S. Geological Survey

Authors and credits

All materials in this resource — both workshop notebooks and the presentation — were developed by Gwen Hover (Aquaveo), Daniel Ames (BYU), and Sudip Pathak (BYU).

Presented at the Tethys Platform Summit, Chicago, IL, June 17–18, 2026.

This research was supported by the Cooperative Institute for Research to Operations in Hydrology (CIROH) with funding under award NA22NWS4320003 from the NOAA Cooperative Institute Program. The statements, findings, conclusions, and recommendations are those of the author(s) and do not necessarily reflect the opinions of NOAA.