Flood Forecasting API — surface map

Overview

Live discovery revision 20261005 differs from the committed baseline 20260921. Observations checked 2026-09-24; page built 2026-10-08 09:34 UTC.

Base URL https://floodforecasting.googleapis.com/v1. Every call needs ?key=<API key> (a Google Cloud API key with the Flood Forecasting API enabled on its project); an unkeyed call, including the discovery document, returns 403 PERMISSION_DENIED.
Quota: 200 requests per minute per project (API FAQ). Google says higher limits can be discussed case by case.
Data licence: CC BY 4.0 (developer site). The API is still labelled a pilot; breaking changes are announced in advance.
The discovery document (/$discovery/rest?version=v1) is the authoritative schema and is what this page is generated from. Its revision is a date; 20260921 at the time of writing.
Two id spaces: real gauges (<source>_<id>, e.g. GRDC) and virtual gauges (hybas_<HydroBASINS id>). Roughly 5,000 quality-verified gauges in ~100 countries and 240,000+ non-verified ones in 150+ countries (API FAQ). Quality-verified is the default nearly everywhere; includeNonQualityVerified opts in.
No history endpoint exists for events. cutoffTime on the two flood-status methods is the only look-back in the API, and its floor is 2025-08-01. Anything before that lives in the Runoff Reanalysis & Reforecast (1980–2023) and Inundation History (1999–2020) GCS buckets, which are not part of this API.
Fields with the proto default are omitted from JSON: a flood status with no severity key means SEVERITY_UNSPECIFIED, not UNKNOWN; a gauge without river simply has no river name.
Polygons come back as KML strings, never GeoJSON. One Placemark, optionally a MultiGeometry, then Polygon elements each with an outer ring and zero or more inner rings; coordinates are lon,lat[,alt]. The repo's fetch_snapshot.py has a 20-line converter.
Transient 503 UNAVAILABLE responses happen on serializedPolygons.get in the middle of an otherwise healthy run (seen 2026-09-24 on a CI pull of ~180 requests). Retry with backoff; do not treat a single 503 as an outage.

Endpoints

Group		Path	Description
Event products	POST	`/v1/significantEvents:search`	Search for latest significant events.
Event products	POST	`/v1/flashFloods:search`	Search for flash floods. Returns the latest currently active or forecasted flash flood events. See https://support.google.com/flood-hub/answer/16811681 for more details.
Event products	GET	`/v1/floodStatus:queryLatestFloodStatusByGaugeIds`	Query latest flood status by gauge ids.
Event products	POST	`/v1/floodStatus:searchLatestFloodStatusByArea`	Search latest flood status by geographical area. Note: Returns flood statuses whose gauge is within the given area, as opposed to e.g., affected area intersecting with the given area. This is subject to change in the future.
Event products	GET	`/v1/{+name}`	Get a serialized polygon. IDs for these will appear in other API Responses, and you'll be able to use these IDs here. For example, see InundationMap in FloodStatus.
Gauge products	GET	`/v1/gauges:batchGet`	Get metadata about multiple gauges.
Gauge products	GET	`/v1/{+name}`	Get metadata about a gauge.
Gauge products	GET	`/v1/gauges:queryGaugeForecasts`	Query gauge forecasts.
Gauge products	POST	`/v1/gauges:searchGaugesByArea`	Search for gauges by geographical area. Note: Gauges are occasionally added or removed, so the result of this API should not be cached or stored for long periods of time. Consider no more than a day to be relatively safe.
Gauge products	GET	`/v1/gaugeModels:batchGet`	Get the current hydrological model metadata for multiple gauges.
Gauge products	GET	`/v1/{+name}`	Get the current hydrological model metadata for a given gauge.

Event products

POST `/v1/significantEvents:search`

floodforecasting.significantEvents.search

Search for latest significant events.

Request body — SearchLatestSignificantEventsRequest

Field	Type	Description
`pageSize`	integer	Required. The maximum number of events to return. The service may return fewer than this value. If unspecified, at most 1,000 events will be returned. The maximum value is 1,000; values above 1,000 will be coerced to 1,000. The maximum value is currently not enforced by the API, but will be in the future.
`pageToken`	string	Optional. A page token, received from a previous `SearchLatestSignificantEvents` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchLatestSignificantEvents` must match the call that provided the page token.

Response — SearchLatestSignificantEventsResponse

Field	Type	Description
`nextPageToken`	string	Optional. A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.
`significantEvents`	array of SignificantEvent	The significant events.

Observed behaviour

Returns only the events that are current (predicted to be ongoing or starting). There is no way to ask for past events, and no filter of any kind: countryCodes, regionCode, cutoffTime and loop all return 400 Unknown name. Filter client-side on affectedCountryCodes.
Observed 2026-09-24: 3 events worldwide (India; Nepal+India; Cambodia+Thailand+Myanmar), 45 M people and 124,000 km² between them, each listing 200–440 gauges. Two pages were returned for 3 events: the last page was empty but still carried a token on the first page.
Events are defined in the significant-events help article as clustered basins whose gauge discharge forecasts exceed danger level, with WorldPop for population. Gauges listed are overwhelmingly non-quality-verified (19 of 20 sampled), which is the point: the product exists for places without verified gauges.
eventTrackingIds is new since the team's March 2026 feedback asked for an event id. It is best-effort: an event that drops below Google's internal score and comes back gets a new id, and merged events carry several. Treat it as a join key across daily snapshots, not as an identity guarantee.
Still missing from the March 2026 asks: event-level statistics such as day of peak, maximum population, or cumulative extent. affectedPopulation and areaKm2 are the forward-looking totals for the remaining event, so they shrink as an event ends.

POST `/v1/flashFloods:search`

floodforecasting.flashFloods.search

Search for flash floods. Returns the latest currently active or forecasted flash flood events. See https://support.google.com/flood-hub/answer/16811681 for more details.

Request body — SearchLatestFlashFloodsRequest

Field	Type	Description
`countryCodes`	array of string	Optional. The country codes to search for flash floods. In ISO 3166 alpha-2 format, e.g. "US". If not provided, flash floods for all countries will be returned.
`pageSize`	integer	Optional. The maximum number of events to return. The service may return fewer than this value. If unspecified, at most 10,000 events will be returned. The maximum value is 10,000; values above 10,000 will be coerced to 10,000.
`pageToken`	string	Optional. A page token, received from a previous `SearchLatestFlashFloods` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchLatestFlashFloods` must match the call that provided the page token.

Response — SearchLatestFlashFloodsResponse

Field	Type	Description
`flashFloodEvents`	array of FlashFloodEvent	The flash flood events found based on the request criteria.
`nextPageToken`	string	Optional. A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

Observed behaviour

One issue per day (observed forecastIssueTime 06:33 UTC) valid for forecastPeriodHours = 24. Every event carries at least one of likelyAffectedPolygonId / highlyLikelyAffectedPolygonId; eventPolygonId (their union) is only present when both exist.
Observed 2026-09-24: 132 events in 25 countries, 22 of them with a highly-likely polygon. Polygons are small (a few hundred bytes of KML, one ring) — urban tiles rather than basins.
countryCodes filter works and is the only filter. The likely/highly-likely thresholds are not defined anywhere public; the help article says the model covers urban areas and rural areas with flood history, weather-driven floods only (no dam breaks or glacial outbursts).
Not answered since March 2026: the population-density mask, the sources of the training flood catalogue, and skill / false-alarm rates for the two likelihood classes.

GET `/v1/floodStatus:queryLatestFloodStatusByGaugeIds`

floodforecasting.floodStatus.queryLatestFloodStatusByGaugeIds

Query latest flood status by gauge ids.

Query / path parameters

Parameter	Type	Description
`cutoffTime`	string · query · optional	Optional. The cutoff time for the flood statuses. When provided, the latest (last published) flood statuses as of the cut-off time will be returned. When not provided, the latest published flood statuses as of now will be returned. The minimum allowed cutoff time is 2025-08-01T00:00:00Z. If the cutoff time is before this time, an INVALID_ARGUMENT error will be returned. Represented as ISO 8601, e.g., "2025-10-17T10:34:00Z".
`gaugeIds`	string · query · optional	Required. A list of gauge ids. The supported list size is limited to 20,000. If a list larger than 20,000 is provided it fails with an INVALID_REQUEST error.

Response — QueryLatestFloodStatusByGaugeIdsResponse

Field	Type	Description
`floodStatuses`	array of FloodStatus	The latest flood statuses for the requested gauges.

Observed behaviour

GET with repeated gaugeIds= query parameters, documented limit 20,000 ids; in practice URL length caps a call at a few hundred ids, so chunk (the snapshot script uses 100).
Accepts non-quality-verified gauge ids without any flag — this is how the statuses behind a significant event's gaugeIds are read (49 SEVERE + 1 EXTREME for the first 50 gauges of the India event).
Same cutoffTime semantics and 2025-08-01 floor as the area search.

POST `/v1/floodStatus:searchLatestFloodStatusByArea`

floodforecasting.floodStatus.searchLatestFloodStatusByArea

Search latest flood status by geographical area. Note: Returns flood statuses whose **gauge** is within the given area, as opposed to e.g., affected area intersecting with the given area. This is subject to change in the future.

Request body — SearchLatestFloodStatusByAreaRequest

Field	Type	Description
`cutoffTime`	string	Optional. The cutoff time for the flood statuses. When provided, the latest (last published) flood statuses as of the cut-off time will be returned. When not provided, the latest published flood statuses as of now will be returned. The minimum allowed cutoff time is 2025-08-01T00:00:00Z. If the cutoff time is before this time, an INVALID_ARGUMENT error will be returned. Represented as ISO 8601, e.g., "2025-10-17T10:34:00Z".
`includeNonQualityVerified`	boolean	Optional. Include in the result gauges that aren't quality verified. Please use with caution. Default is false.
`loop`	Loop	The loop by which to query flood statuses.
`pageSize`	integer	Optional. The maximum number of flood statuses to return. The service may return fewer than this value. If unspecified, at most 20,000 flood statuses will be returned. The maximum value is 20,000; values above 20,000 will be coerced to 20,000.
`pageToken`	string	Optional. A page token, received from a previous `SearchLatestFloodStatusByArea` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchLatestFloodStatusByArea` must match the call that provided the page token.
`regionCode`	string	The region by which to query flood statuses. Using CLDR, e.g., 'US'.

Response — SearchLatestFloodStatusByAreaResponse

Field	Type	Description
`floodStatuses`	array of FloodStatus	The latest flood statuses in the requested area. Currently, this is determined by the location of the gauges, this is subject to change in the future.
`nextPageToken`	string	Optional. A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

Observed behaviour

The area is matched on the gauge point, not on the affected polygon — a status whose inundation map crosses into your area is not returned unless its gauge is inside. Google flags this as subject to change.
Exactly one of regionCode (CLDR country code) or loop must be given. A loop spanning 180° of longitude or more is ambiguous on the sphere: a single world loop returned 0 statuses and two 180°-wide hemispheres each returned the same 2,103. Four 90°-wide quadrants (±85° latitude) return distinct sets and together give every quality-verified gauge: 5,170 on 2026-09-24 (≈ 80 non-NO_FLOODING). The whole sweep is 4–8 requests.
Pagination: pageSize up to 20,000 is honoured for large loops, but a trailing empty page with a nextPageToken is common, and regionCode: NG returned 53 statuses on a first page with a token whose next page was empty. Always loop until the token is absent.
cutoffTime gives the latest status *as of* that instant, floor 2025-08-01T00:00Z. With a daily cutoff this is the only way in the API to reconstruct a gauge's status history, at one request per country-day (or per quadrant-day).
inundationMapSet was absent from every Nigerian and every global status sampled; serializedNotificationPolygonId appeared only on the single ABOVE_NORMAL Nigerian status. Inundation maps are therefore rare in the API even where Flood Hub shows them.

GET `/v1/{+name}`

floodforecasting.serializedPolygons.get

Get a serialized polygon. IDs for these will appear in other API Responses, and you'll be able to use these IDs here. For example, see InundationMap in FloodStatus.

Query / path parameters

Parameter	Type	Description
`name`	string · path · required	Required. The name of the serialized polygon to retrieve. Name format: serializedPolygons/{polygon_id}

Response — SerializedPolygon

Field	Type	Description
`kml`	string	The KML string representation of the polygon.
`polygonId`	string	The id of the polygon.

Observed behaviour

name is serializedPolygons/{polygonId}; ids are opaque base64-looking strings that appear in flood statuses, significant events and flash floods. Response is {polygonId, kml} only.
Sizes observed: a significant-event polygon 120 kB of KML (4 polygons, 5,400 vertices); a flash-flood polygon 0.6 kB. Fetching every polygon of a day's flash floods is ~150 requests.

Gauge products

GET `/v1/gauges:batchGet`

floodforecasting.gauges.batchGet

Get metadata about multiple gauges.

Query / path parameters

Parameter	Type	Description
`names`	string · query · optional	Required. The gauge names to retrieve. Name format: gauges/{gauge_id}. The supported list size is limited to 100,000. If a list larger than 100,000 is provided it fails with an INVALID_REQUEST error.

Response — BatchGetGaugesResponse

Field	Type	Description
`gauges`	array of Gauge	The requested gauges.

Observed behaviour

GET with repeated names=gauges/{gaugeId}. Works for non-quality-verified gauges (returns qualityVerified: false, hasModel: true, source: HYBAS). Still no field for the 'high confidence' flag the team asked for in March 2026 beyond qualityVerified itself.

GET `/v1/{+name}`

floodforecasting.gauges.get

Get metadata about a gauge.

Query / path parameters

Parameter	Type	Description
`name`	string · path · required	Required. The name of the gauge to retrieve. Name format: gauges/{gauge_id}.

Response — Gauge

Field	Type	Description
`countryCode`	string	The country code of the gauge's country (ISO 3166 Alpha-2).
`gaugeId`	string	The ID of the gauge.
`hasModel`	boolean	This field is true if the gauge has a model. If the gauge has a model, it's possible to get this gauges's GaugeModel using GetGaugeModel or BatchGetGaugeModels. And also getting its forecasts using QueryGaugeForecasts.
`location`	LatLng	The physical location of the gauge.
`qualityVerified`	boolean	This field is true if the gauge does not have a model, or if it has a model and the model is quality-verified. Please use with caution when this value is set to false.
`river`	string	The gauge's river name in English. Not always present.
`siteName`	string	The name of the site at which this gauge is located, in English. This is not a unique identifier; there may be several gauges in nearby locations with the same site name. Not always present.
`source`	string	The organization responsible for the data of this gauge, e.g. GRDC, CWC, etc.

GET `/v1/gauges:queryGaugeForecasts`

floodforecasting.gauges.queryGaugeForecasts

Query gauge forecasts.

Query / path parameters

Parameter	Type	Description
`gaugeIds`	string · query · optional	Required. A list of gauge ids. The supported list size is limited to 500. If a list larger than 500 is provided it fails with an INVALID_REQUEST error.
`issuedTimeEnd`	string · query · optional	Optional. The latest forecast issued time as string (ISO 8601), e.g. "2023-06-17T10:34:00Z" or a date string e.g. "2023-10-13". Default is now.
`issuedTimeStart`	string · query · optional	Optional. The earliest forecast issued time as string (ISO 8601), e.g. "2023-06-17T10:34:00Z" or a date string e.g. "2023-10-13". Start time cannot be earlier than "2023-10-01". Default is one week ago.

Response — QueryGaugeForecastsResponse

Field	Type	Description
`forecasts`	object	A map from gauge id to forecast set.

Observed behaviour

The team's operational endpoint (ds-aa-som-floods, ds-aa-nga-flooding monitoring). Returns the recent issues per gauge, each with values from issue−2 to issue+5 days for discharge models; leadtime = valid day − issue day.
A batch call 404s if *any* requested gauge is not served; the SOM monitor falls back to per-gauge calls and keeps an explicit list of ids the API stopped serving.

POST `/v1/gauges:searchGaugesByArea`

floodforecasting.gauges.searchGaugesByArea

Search for gauges by geographical area. Note: Gauges are occasionally added or removed, so the result of this API should not be cached or stored for long periods of time. Consider no more than a day to be relatively safe.

Request body — SearchGaugesByAreaRequest

Field	Type	Description
`includeGaugesWithoutHydroModel`	boolean	Optional. Include in the result gauges that don't have a Google in-house hydro model. Default is false.
`includeNonQualityVerified`	boolean	Optional. Include in the result gauges that aren't quality verified. Please use with caution. Default is false.
`loop`	Loop	Search for all gauges within a loop (a simple spherical polygon, see Loop).
`pageSize`	integer	Optional. The maximum number of gauges to return. The service may return fewer than this value. If unspecified, at most 50,000 gauges will be returned. The maximum value is 50,000; values above 50,000 will be coerced to 50,000.
`pageToken`	string	Optional. A page token, received from a previous `SearchGauges` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchGauges` must match the call that provided the page token.
`regionCode`	string	Search for all gauges within a region by region code. Use https://cldr.unicode.org/ (list https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).

Response — SearchGaugesByAreaResponse

Field	Type	Description
`gauges`	array of Gauge	Gauges found in the requested area.
`nextPageToken`	string	Optional. A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

Observed behaviour

Same regionCode / loop choice as the flood-status search, plus includeGaugesWithoutModel and includeNonQualityVerified. Used by ds-aa-nga-flooding to enumerate HYBAS gauges over Nigeria.

GET `/v1/gaugeModels:batchGet`

floodforecasting.gaugeModels.batchGet

Get the current hydrological model metadata for multiple gauges.

Query / path parameters

Parameter	Type	Description
`names`	string · query · optional	Required. The gauge model names to retrieve. Name format: gaugeModels/{gauge_id}. The supported list size is limited to 20,000. If a list larger than 20,000 is provided it fails with an INVALID_REQUEST error.

Response — BatchGetGaugeModelsResponse

Field	Type	Description
`gaugeModels`	array of GaugeModel	The requested gauge models.

Observed behaviour

Thresholds (warningLevel, dangerLevel, optional extremeDangerLevel) and the unit (METERS or CUBIC_METERS_PER_SECOND). gaugeModelId changes when a gauge's model is replaced, so stored thresholds should be keyed on it.

GET `/v1/{+name}`

floodforecasting.gaugeModels.get

Get the current hydrological model metadata for a given gauge.

Query / path parameters

Parameter	Type	Description
`name`	string · path · required	Required. The gauge model name to retrieve. Name format: gaugeModels/{gauge_id}.

Response — GaugeModel

Field	Type	Description
`gaugeId`	string	The ID of the gauge.
`gaugeModelId`	string	The ID of the gauge's model. From time to time, the model for a gauge may change, and in that case we'll assign a new ID and new thresholds to the new model. Please use caution when comparing old forecasts to new ones if they were produced by different models.
`gaugeValueUnit`	string	The value unit of the gauge's model. `GAUGE_VALUE_UNIT_UNSPECIFIED` — Default value. This value is unused. `METERS` — Meters. `CUBIC_METERS_PER_SECOND` — Cubic meters per second.
`qualityVerified`	boolean	Whether this model is quality verified. Please use with caution when this value is set to false.
`thresholds`	Thresholds	The thresholds of the gauge.

Since the March 2026 feedback to Google

The team sent Google structured feedback on the significant-events and flash-flood products in March 2026 (internal Drive doc). What the API answers now, and what it still does not.

Answered

Event identifier: eventTrackingIds on SignificantEvent (best-effort, may change on re-threshold or merge).
Flash floods are exposed in the API (flashFloods:search) with the two likelihood classes as separate polygons and a countryCodes filter.
Non-quality-verified gauges are reachable everywhere (includeNonQualityVerified, batchGet, status by ids).

Still open

No historical significant events or flash floods: the API is strictly 'latest'. A daily snapshot is the only way to build the record HDX Signals would need.
No event-level peak or cumulative statistics; population and area are forward-looking remainders.
No skill or false-alarm figures for either likelihood class of flash floods, and no published population-density mask.
No richer gauge confidence metadata than the boolean qualityVerified.

Schemas

SearchLatestFlashFloodsRequest

The request of SearchLatestFlashFloods.

Field	Type	Description
`countryCodes`	array of string	Optional. The country codes to search for flash floods. In ISO 3166 alpha-2 format, e.g. "US". If not provided, flash floods for all countries will be returned.
`pageSize`	integer	Optional. The maximum number of events to return. The service may return fewer than this value. If unspecified, at most 10,000 events will be returned. The maximum value is 10,000; values above 10,000 will be coerced to 10,000.
`pageToken`	string	Optional. A page token, received from a previous `SearchLatestFlashFloods` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchLatestFlashFloods` must match the call that provided the page token.

SearchLatestFlashFloodsResponse

The response of SearchLatestFlashFloods.

Field	Type	Description
`flashFloodEvents`	array of FlashFloodEvent	The flash flood events found based on the request criteria.
`nextPageToken`	string	Optional. A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

FlashFloodEvent

A flash flood event. It represents a timeframe that starts at forecast_issue_time and lasts for forecast_period_hours, within which we expect a flash flood to occur.

Field	Type	Description
`affectedCountryCodes`	array of string	The countries predicted to be affected by the event, in ISO 3166 alpha-2 format, e.g. "US".
`eventPolygonId`	string	The polygon ID of the border area of the event. This is the union of the likely and highly likely polygons. The polygon ID can be sent to GetSerializedPolygon to retrieve the polygon of the border area of the event.
`forecastIssueTime`	string	The time where this forecast was issued. Represented as ISO 8601, e.g., "2025-10-17T10:34:00Z".
`forecastPeriodHours`	integer	How long the forecast is valid for (in hours).
`highlyLikelyAffectedPolygonId`	string	The polygon of the area that is highly likely to be affected by a flash flood. The polygon ID can be sent to GetSerializedPolygon to retrieve the polygon of the area of the event.
`likelyAffectedPolygonId`	string	The polygon of the area that is likely to be affected by a flash flood. The polygon ID can be sent to GetSerializedPolygon to retrieve the polygon of the area of the event.

Observed behaviour

No severity, probability or population fields: the two likelihood classes are encoded purely by which polygon ids are present.

QueryLatestFloodStatusByGaugeIdsResponse

The response of QueryLatestFloodStatusByGaugeIds.

Field	Type	Description
`floodStatuses`	array of FloodStatus	The latest flood statuses for the requested gauges.

FloodStatus

A Flood Status issued by the system. Represents the flooding status forecasted by the system for an area, with attributes such as severity, the forecast change, inundation maps and others. See below for more details.

Field	Type	Description
`forecastChange`	ForecastChange	The forecast value change from the last known state to the forecast. Currently only available for Water Level models.
`forecastTimeRange`	TimeRange	The time range for which the forecast is predicting.
`forecastTrend`	string	The trend of the forecast. `FORECAST_TREND_UNSPECIFIED` — Default value. This value is unused. `RISE` — This indicates a rise in the forecasted value. `FALL` — This indicates a fall in the forecasted value. `NO_CHANGE` — This indicates no change in the forecasted value.
`gaugeId`	string	The id of the gauge this status was issued for.
`gaugeLocation`	LatLng	The location of the gauge this status was issued for.
`inundationMapSet`	InundationMapSet	The inferred inundation map set.
`issuedTime`	string	The time this status was issued as string (ISO 8601), e.g., "2023-06-17T10:34:00Z".
`mapInferenceType`	string	The type of inference this map was created by. `MAP_INFERENCE_TYPE_UNSPECIFIED` — Default value. This value is unused. `MODEL` — This indicates that this inference was created using a model. `IMAGE_CLASSIFICATION` — This indicates that this inference was created using an image classification.
`qualityVerified`	boolean	True if the gauge this flood status was issued for does not have a model, or if it has a model and the model is quality-verified. Please use with caution when this value is set to false.
`serializedNotificationPolygonId`	string	An ID of the serialized notification polygon, which represents the geographic area Google uses to determine when to alert its users. Use GetSerializedPolygon to get the serialized polygon itself.
`severity`	string	The severity of the status. `SEVERITY_UNSPECIFIED` — Default value. This value is unused. `EXTREME` — This indicates a forecasted extreme status. `SEVERE` — This indicates a forecasted severe status. `ABOVE_NORMAL` — This indicates a forecasted above normal status. `NO_FLOODING` — This indicates a forecast of no flooding. `UNKNOWN` — This indicates that we don't have enough information to determine the severity.
`source`	string	The organization responsible for the data of this gauge, e.g., GRDC, CWC, etc.

Observed behaviour

forecastChange (a water-level rise/fall band) exists only for stage (METERS) models; every HYBAS virtual gauge is a discharge model, so it is absent for them.
mapInferenceType is populated only alongside inundationMapSet.

ForecastChange

The forecasted value change from the last known state to the forecast. Currently only available for Water Level models.

Field	Type	Description
`referenceTimeRange`	TimeRange	Time range of the last known state, from which we predict the value change from. For example, we may have a reference time range set to yesterday, and a value change of 25-30cm. This means the water level rise of 25-30cm is compared to its value yesterday, not from its value now.
`valueChange`	ValueChange	The forecasted change in values.

TimeRange

A time range.

Field	Type	Description
`end`	string	The end of the time range. Represented as ISO 8601, e.g., "2023-06-17T10:34:00Z".
`start`	string	The start of the time range. Represented as ISO 8601, e.g., "2023-06-17T10:34:00Z".

ValueChange

The forecasted change in values - an upper and lower bound.

Field	Type	Description
`lowerBound`	number	The lower bound of the forecast change in meters. If the change is between 20 and 30, this value would be 20. If the change is between -30 and -20, this value would be -30.
`upperBound`	number	The upper bound of the forecast change in meters. If the change is between 20 and 30, this value would be 30. If the change is between -30 and -20, this value would be -20.

LatLng

An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.

Field	Type	Description
`latitude`	number	The latitude in degrees. It must be in the range [-90.0, +90.0].
`longitude`	number	The longitude in degrees. It must be in the range [-180.0, +180.0].

InundationMapSet

A set of inundation maps.

Field	Type	Description
`inundationMapType`	string	The type of the inundation map. `INUNDATION_MAP_TYPE_UNSPECIFIED` — Default value. This value is unused. `PROBABILITY` — A map of type probability. The InundationLevel represents the map probability - high/medium/low probability of flooding. The high probability polygon is contained within the medium probability polygon and the medium probability polygon is contained within the low probability polygon. `DEPTH` — A map of type depth. The InundationLevel represents the map depth - high/medium/low depth per location. The high depth polygon is contained within the medium depth polygon and the medium depth polygon is contained within the low depth polygon.
`inundationMaps`	array of InundationMap	The inundation maps, one for each inundation level.
`inundationMapsTimeRange`	TimeRange	The time range of the state to which the inundation maps refer.

InundationMap

One inundation map.

Field	Type	Description
`level`	string	The level of the inundation map - See documentation based on the InundationMapType. `INUNDATION_LEVEL_UNSPECIFIED` — Default value. This value is unused. `HIGH` — See documentation based on the InundationMapType. `MEDIUM` — See documentation based on the InundationMapType. `LOW` — See documentation based on the InundationMapType.
`serializedPolygonId`	string	An ID of the serialized polygon representing this inundation risk map. Use GetSerializedPolygon to get the serialized polygon itself.

SearchLatestFloodStatusByAreaRequest

The request of SearchLatestFloodStatusByArea.

Field	Type	Description
`cutoffTime`	string	Optional. The cutoff time for the flood statuses. When provided, the latest (last published) flood statuses as of the cut-off time will be returned. When not provided, the latest published flood statuses as of now will be returned. The minimum allowed cutoff time is 2025-08-01T00:00:00Z. If the cutoff time is before this time, an INVALID_ARGUMENT error will be returned. Represented as ISO 8601, e.g., "2025-10-17T10:34:00Z".
`includeNonQualityVerified`	boolean	Optional. Include in the result gauges that aren't quality verified. Please use with caution. Default is false.
`loop`	Loop	The loop by which to query flood statuses.
`pageSize`	integer	Optional. The maximum number of flood statuses to return. The service may return fewer than this value. If unspecified, at most 20,000 flood statuses will be returned. The maximum value is 20,000; values above 20,000 will be coerced to 20,000.
`pageToken`	string	Optional. A page token, received from a previous `SearchLatestFloodStatusByArea` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchLatestFloodStatusByArea` must match the call that provided the page token.
`regionCode`	string	The region by which to query flood statuses. Using CLDR, e.g., 'US'.

Loop

A loop on the map. Represents a simple spherical polygon. It consists of a single chain of vertices where the first vertex is implicitly connected to the last.

Field	Type	Description
`vertices`	array of LatLng	Required. The vertices of the loop.

SearchLatestFloodStatusByAreaResponse

The response of SearchLatestFloodStatusByArea.

Field	Type	Description
`floodStatuses`	array of FloodStatus	The latest flood statuses in the requested area. Currently, this is determined by the location of the gauges, this is subject to change in the future.
`nextPageToken`	string	Optional. A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

BatchGetGaugeModelsResponse

The response of BatchGetGaugeModels.

Field	Type	Description
`gaugeModels`	array of GaugeModel	The requested gauge models.

GaugeModel

Metadata of a gauge's model.

Field	Type	Description
`gaugeId`	string	The ID of the gauge.
`gaugeModelId`	string	The ID of the gauge's model. From time to time, the model for a gauge may change, and in that case we'll assign a new ID and new thresholds to the new model. Please use caution when comparing old forecasts to new ones if they were produced by different models.
`gaugeValueUnit`	string	The value unit of the gauge's model. `GAUGE_VALUE_UNIT_UNSPECIFIED` — Default value. This value is unused. `METERS` — Meters. `CUBIC_METERS_PER_SECOND` — Cubic meters per second.
`qualityVerified`	boolean	Whether this model is quality verified. Please use with caution when this value is set to false.
`thresholds`	Thresholds	The thresholds of the gauge.

Thresholds

Thresholds of a gauge's model.

Field	Type	Description
`dangerLevel`	number	Danger level.
`extremeDangerLevel`	number	Extreme danger level. Not always present.
`warningLevel`	number	Warning level.

BatchGetGaugesResponse

The response of BatchGetGauges.

Field	Type	Description
`gauges`	array of Gauge	The requested gauges.

Gauge

Metadata of a gauge.

Field	Type	Description
`countryCode`	string	The country code of the gauge's country (ISO 3166 Alpha-2).
`gaugeId`	string	The ID of the gauge.
`hasModel`	boolean	This field is true if the gauge has a model. If the gauge has a model, it's possible to get this gauges's GaugeModel using GetGaugeModel or BatchGetGaugeModels. And also getting its forecasts using QueryGaugeForecasts.
`location`	LatLng	The physical location of the gauge.
`qualityVerified`	boolean	This field is true if the gauge does not have a model, or if it has a model and the model is quality-verified. Please use with caution when this value is set to false.
`river`	string	The gauge's river name in English. Not always present.
`siteName`	string	The name of the site at which this gauge is located, in English. This is not a unique identifier; there may be several gauges in nearby locations with the same site name. Not always present.
`source`	string	The organization responsible for the data of this gauge, e.g. GRDC, CWC, etc.

QueryGaugeForecastsResponse

The response of QueryGaugeForecasts.

Field	Type	Description
`forecasts`	object	A map from gauge id to forecast set.

SearchGaugesByAreaRequest

The request of SearchGaugesByArea.

Field	Type	Description
`includeGaugesWithoutHydroModel`	boolean	Optional. Include in the result gauges that don't have a Google in-house hydro model. Default is false.
`includeNonQualityVerified`	boolean	Optional. Include in the result gauges that aren't quality verified. Please use with caution. Default is false.
`loop`	Loop	Search for all gauges within a loop (a simple spherical polygon, see Loop).
`pageSize`	integer	Optional. The maximum number of gauges to return. The service may return fewer than this value. If unspecified, at most 50,000 gauges will be returned. The maximum value is 50,000; values above 50,000 will be coerced to 50,000.
`pageToken`	string	Optional. A page token, received from a previous `SearchGauges` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchGauges` must match the call that provided the page token.
`regionCode`	string	Search for all gauges within a region by region code. Use https://cldr.unicode.org/ (list https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).

SearchGaugesByAreaResponse

The response of SearchGaugesByArea.

Field	Type	Description
`gauges`	array of Gauge	Gauges found in the requested area.
`nextPageToken`	string	Optional. A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

SerializedPolygon

A serialized polygon.

Field	Type	Description
`kml`	string	The KML string representation of the polygon.
`polygonId`	string	The id of the polygon.

SearchLatestSignificantEventsRequest

The request of SearchLatestSignificantEvents.

Field	Type	Description
`pageSize`	integer	Required. The maximum number of events to return. The service may return fewer than this value. If unspecified, at most 1,000 events will be returned. The maximum value is 1,000; values above 1,000 will be coerced to 1,000. The maximum value is currently not enforced by the API, but will be in the future.
`pageToken`	string	Optional. A page token, received from a previous `SearchLatestSignificantEvents` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchLatestSignificantEvents` must match the call that provided the page token.

SearchLatestSignificantEventsResponse

The response of SearchLatestSignificantEvents.

Field	Type	Description
`nextPageToken`	string	Optional. A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.
`significantEvents`	array of SignificantEvent	The significant events.

SignificantEvent

Significant events are predicted flood events with high probability and high impact. They cover places where we don't have quality-verified gauges.

Field	Type	Description
`affectedCountryCodes`	array of string	The affected countries, in ISO 3166 alpha-2 format. The list contains all countries that are predicted to be affected by the event, going forward.
`affectedPopulation`	integer	The estimated population in the affected area. It represents the population that is predicted to be affected by the event, going forward.
`areaKm2`	number	The area of the event in km^2. It represents the area that is predicted to be affected by the event, going forward.
`eventInterval`	SignificantEventInterval	Start and end time of the event.
`eventPolygonId`	string	A polygon ID that can be sent to GetSerializedPolygon to retrieve the polygon of the area of the event.
`eventTrackingIds`	array of string	The IDs used to track this event across time. Caveats: 1. Multiple IDs may exist for merged events. 2. It is not guaranteed that the tracking ID will fully persist across the event lifetime, it is best-effort. Background: We have an internal scoring and thresholding settings to define a Significant Event. If an event goes above our thresholds and then below and then above again, it gets a new tracking ID the seoncd time it goes above.
`gaugeIds`	array of string	A list of gauges in the event. The list contains all gauges that are predicted to be affected by the event, going forward.

Observed behaviour

eventInterval has startTime plus either endTime (event predicted to finish inside the forecast horizon) or minimumEndTime (still ongoing at the horizon) — never both.

SignificantEventInterval

A time interval of a significant event.

Field	Type	Description
`endTime`	string	The end time of the event. In ISO 8601 format, e.g. "2025-03-25T10:34:00Z".
`minimumEndTime`	string	The minimum end time of the event. In ISO 8601 format, e.g. "2025-03-25T10:34:00Z". The event is predicted to last longer than the model's lead time. We don't know the actual end time, but the event is predicted to last at least until this time.
`startTime`	string	The start time of the event. In ISO 8601 format, e.g. "2025-03-17T10:34:00Z".

Forecast

A single gauge's forecast for several lead times. For example, a forecast could have issue time of 5pm, and include forecasts for 6pm, 7pm, 8pm, etc. Note: Some of the forecast ranges can potentially be earlier than the issued time. This can happen due to e.g., lags in input data for the model. With the above example, it could be that the issue time is 5pm, and the forecast ranges are for 4pm, 5pm, 6pm, etc. Note: Ranges vary in length, and in distance between them. Some examples of possible ranges are: 1. [5pm - 5pm], [6pm - 6pm], [7pm - 7pm] 2. [Mar 1 12am - Mar 2 12am], [Mar 2 12am - Mar 3 12am], [Mar 3 12am - Mar 4 12am]

Field	Type	Description
`forecastRanges`	array of ForecastTimedValue	A forecast consists of several "forecast ranges", which are different forecast values pertaining to different time ranges. When the start and end of a range are equal, it means it's a time instant.
`gaugeId`	string	The ID of the gauge this forecast is for.
`issuedTime`	string	The issued time of the forecast (ISO 8601), e.g. "2023-06-17T10:34:00Z". The issued time is the time the forecast was generated.

ForecastSet

A set of forecasts for a gauge.

Field	Type	Description
`forecasts`	array of Forecast	The forecasts.

ForecastTimedValue

A forecast value pertaining to a time range. Its units are defined by the GaugeModel it is associated with. If the start and end are equal, it means it's a time instant.

Field	Type	Description
`forecastEndTime`	string	The end of the interval.
`forecastStartTime`	string	The start of the interval.
`value`	number	The value of the forecast.

Overview

Endpoints

Event products

POST /v1/significantEvents:search

Request body — SearchLatestSignificantEventsRequest

Response — SearchLatestSignificantEventsResponse

Observed behaviour

POST /v1/flashFloods:search

Request body — SearchLatestFlashFloodsRequest

Response — SearchLatestFlashFloodsResponse

Observed behaviour

GET /v1/floodStatus:queryLatestFloodStatusByGaugeIds

Query / path parameters

Response — QueryLatestFloodStatusByGaugeIdsResponse

Observed behaviour

POST /v1/floodStatus:searchLatestFloodStatusByArea

Request body — SearchLatestFloodStatusByAreaRequest

Response — SearchLatestFloodStatusByAreaResponse

Observed behaviour

GET /v1/{+name}

Query / path parameters

Response — SerializedPolygon

Observed behaviour

Gauge products

GET /v1/gauges:batchGet

Query / path parameters

Response — BatchGetGaugesResponse

Observed behaviour

GET /v1/{+name}

Query / path parameters

Response — Gauge

GET /v1/gauges:queryGaugeForecasts

Query / path parameters

Response — QueryGaugeForecastsResponse

Observed behaviour

POST /v1/gauges:searchGaugesByArea

Request body — SearchGaugesByAreaRequest

Response — SearchGaugesByAreaResponse

Observed behaviour

GET /v1/gaugeModels:batchGet

Query / path parameters

Response — BatchGetGaugeModelsResponse

Observed behaviour

GET /v1/{+name}

Query / path parameters

Response — GaugeModel

Since the March 2026 feedback to Google

Answered

Still open

Schemas

SearchLatestFlashFloodsRequest

SearchLatestFlashFloodsResponse

FlashFloodEvent

Observed behaviour

QueryLatestFloodStatusByGaugeIdsResponse

FloodStatus

Observed behaviour

ForecastChange

TimeRange

ValueChange

LatLng

InundationMapSet

InundationMap

SearchLatestFloodStatusByAreaRequest

Loop

SearchLatestFloodStatusByAreaResponse

BatchGetGaugeModelsResponse

GaugeModel

Thresholds

BatchGetGaugesResponse

Gauge

QueryGaugeForecastsResponse

SearchGaugesByAreaRequest

SearchGaugesByAreaResponse

SerializedPolygon

SearchLatestSignificantEventsRequest

SearchLatestSignificantEventsResponse

SignificantEvent

Observed behaviour

SignificantEventInterval

POST `/v1/significantEvents:search`

POST `/v1/flashFloods:search`

GET `/v1/floodStatus:queryLatestFloodStatusByGaugeIds`

POST `/v1/floodStatus:searchLatestFloodStatusByArea`

GET `/v1/{+name}`

GET `/v1/gauges:batchGet`

GET `/v1/{+name}`

GET `/v1/gauges:queryGaugeForecasts`

POST `/v1/gauges:searchGaugesByArea`

GET `/v1/gaugeModels:batchGet`

GET `/v1/{+name}`