Google Flood Forecasting
Integration with Google's Flood Forecasting API to ingest forward-looking flood predictions, gated by a severity filter and a GeoPop population check before they enter the event pipeline.
Overview
Google Flood Forecasting is TerraGuard's prediction data source. Unlike GDACS, USGS, and NHC — which report events that have already happened or are happening now — Google Flood provides forward-looking riverine and flash-flood forecasts.
Events ingested from this source are flagged with is_prediction = true so the frontend and
notification logic can present them as forecasts rather than confirmed events.
The adapter lives in the Event Processor (tg-event-processor) at
internal/adapter/googleflood/ and polls Google's API on a configurable interval. It is
disabled by default (GOOGLE_FLOOD_ENABLED=false) and enabled per-deployment.
What Google Flood Provides
The adapter consumes three kinds of flood status, each independently toggleable:
| Prediction type | Config toggle | Description |
|---|---|---|
| Gauge forecast | GOOGLE_FLOOD_INCLUDE_GAUGE | River-gauge level forecasts with a severity band |
| Flash flood | GOOGLE_FLOOD_INCLUDE_FLASH | Short-fuse flash-flood likelihood for an area |
| Significant event | GOOGLE_FLOOD_INCLUDE_SIGNIFICANT | Larger-area flood events affecting many people |
API
The adapter calls the Flood Forecasting REST API:
POST https://floodforecasting.googleapis.com/v1/floodStatus:searchLatestFloodStatusByArea| Setting | Env var | Default |
|---|---|---|
| Base URL | GOOGLE_FLOOD_API_URL | https://floodforecasting.googleapis.com |
| API key | GOOGLE_FLOOD_API_KEY | — (required when enabled) |
| Poll interval | GOOGLE_FLOOD_POLL_INTERVAL | 5m |
| Country scope | GOOGLE_FLOOD_COUNTRY_CODES | per-deployment list |
Polygon geometry returned for a prediction is cached by polygon id so repeated polls of the same area don't refetch the shape.
Two-stage filtering
Flood predictions are noisy, so the adapter applies two gates before an event is allowed into the pipeline. This keeps low-impact forecasts out of the system entirely.
Stage 1 — Google-side severity. Gauge forecasts must meet a minimum severity
(GOOGLE_FLOOD_MIN_GAUGE_SEVERITY); flash floods must be classified highly_likely;
significant events must exceed a population estimate (GOOGLE_FLOOD_MIN_SIGNIFICANT_POP).
Stage 2 — GeoPop population gate. After resolving the area centroid, the adapter asks the
GeoPop API how many people live within
GOOGLE_FLOOD_GEOPOP_RADIUS_KM of that point. If fewer than GOOGLE_FLOOD_GEOPOP_MIN_POP,
the prediction is dropped — a forecast over an unpopulated area is not actionable.
Configuration
| Variable | Description |
|---|---|
GOOGLE_FLOOD_ENABLED | Master switch (default false) |
GOOGLE_FLOOD_API_KEY | Flood Forecasting API key |
GOOGLE_FLOOD_API_URL | API base URL |
GOOGLE_FLOOD_POLL_INTERVAL | Poll cadence (default 5m) |
GOOGLE_FLOOD_COUNTRY_CODES | Countries to query |
GOOGLE_FLOOD_MIN_GAUGE_SEVERITY | Stage-1 minimum gauge severity |
GOOGLE_FLOOD_MIN_SIGNIFICANT_POP | Stage-1 minimum population for significant events |
GOOGLE_FLOOD_GEOPOP_MIN_POP | Stage-2 minimum population in radius |
GOOGLE_FLOOD_GEOPOP_RADIUS_KM | Stage-2 population radius |
GOOGLE_FLOOD_INCLUDE_GAUGE / _FLASH / _SIGNIFICANT | Per-type toggles |
The Backend API mirrors a subset for its own scheduled syncing
(GOOGLE_FLOOD_API_KEY, GOOGLE_FLOOD_API_BASE_URL, GOOGLE_FLOOD_POLL_ENABLED,
GOOGLE_FLOOD_FULL_SYNC_CRON, GOOGLE_FLOOD_CRITICAL_POLL_CRON).
Google Flood is the only prediction source in TerraGuard today. Because its output is a
forecast, every event it produces carries is_prediction = true end-to-end — through
scoring, the API, and the frontend — so users always know they are looking at a prediction.
Related
- Event Processing Pipeline — what happens after a prediction is emitted
- GeoPop API — the population gate
- Scoring & Priority — how predictions are scored
NHC
Integration with the National Hurricane Center providing real-time tropical cyclone advisories, position data, intensity measurements, and forecast links.
CAP Webhook Ingestion
How external organizations push Common Alerting Protocol (CAP v1.2) alerts into TerraGuard via an authenticated webhook, and how the per-source transformation layer turns them into disaster events.