Method: gauges.searchGaugesByArea

  • This API allows you to search for gauges within a specific geographical area using a POST request to https://floodforecasting.googleapis.com/v1/gauges:searchGaugesByArea.

  • The request body supports searching by either a region code or a defined loop (spherical polygon), and includes options to set the page size, page token, and whether to include non-quality-verified gauges.

  • The response body contains a list of gauges found in the requested area, along with an optional nextPageToken for retrieving subsequent pages of results.

  • Due to the dynamic nature of gauge data, it is recommended not to cache or store the results from this API for long durations, with a day being the suggested maximum.

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.

HTTP request

POST https://floodforecasting.googleapis.com/v1/gauges:searchGaugesByArea

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "pageSize": integer,
  "pageToken": string,

  // Union field search_by can be only one of the following:
  "regionCode": string,
  "loop": {
    object (Loop)
  }
  // End of list of possible types for union field search_by.
  "includeNonQualityVerified": boolean,
  "includeGaugesWithoutHydroModel": boolean
}
Fields
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.

Union field search_by.

search_by can be only one of the following:
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).
loop

object (Loop)

Search for all gauges within a loop (a simple spherical polygon, see Loop).
includeNonQualityVerified

boolean

Optional. Include in the result gauges that aren't quality verified. Please use with caution. Default is false.
includeGaugesWithoutHydroModel

boolean

Optional. Include in the result gauges that don't have a Google in-house hydro model. Default is false.

Response body

The response of gauges.searchGaugesByArea.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "gauges": [
    {
      object (Gauge)
    }
  ],
  "nextPageToken": string
}
Fields
gauges[]

object (Gauge)

Gauges found in the requested area.
nextPageToken

string

Optional. A token that can be sent as pageToken to retrieve the next page. If this field is omitted, there are no subsequent pages.