Package google.research.floodforecasting.v1

索引

FloodsApi

用于洪水预报的外部 API 服务。

BatchGetGaugeModels

rpc BatchGetGaugeModels(BatchGetGaugeModelsRequest) returns (BatchGetGaugeModelsResponse)

获取多个水位计的当前水文模型元数据。
BatchGetGauges

rpc BatchGetGauges(BatchGetGaugesRequest) returns (BatchGetGaugesResponse)

获取多个流量计的相关元数据。
GetGauge

rpc GetGauge(GetGaugeRequest) returns (Gauge)

获取有关流量表的元数据。
GetGaugeModel

rpc GetGaugeModel(GetGaugeModelRequest) returns (GaugeModel)

获取给定水位计的当前水文模型元数据。
GetSerializedPolygon

rpc GetSerializedPolygon(GetSerializedPolygonRequest) returns (SerializedPolygon)

获取序列化的多边形。这些 ID 将显示在其他 API 响应中，您可以在此处使用这些 ID。例如，请参阅 FloodStatus 中的 InundationMap。
QueryGaugeForecasts

rpc QueryGaugeForecasts(QueryGaugeForecastsRequest) returns (QueryGaugeForecastsResponse)

查询流量计预测。
QueryLatestFloodStatusByGaugeIds

rpc QueryLatestFloodStatusByGaugeIds(QueryLatestFloodStatusByGaugeIdsRequest) returns (QueryLatestFloodStatusByGaugeIdsResponse)

按水位计 ID 查询最新洪水状态。
SearchGaugesByArea

rpc SearchGaugesByArea(SearchGaugesByAreaRequest) returns (SearchGaugesByAreaResponse)

按地理区域搜索水位计。

注意：我们偶尔会添加或移除指标，因此不应缓存或长时间存储此 API 的结果。考虑将不超过一天的期限视为相对安全。
SearchLatestFloodStatusByArea

rpc SearchLatestFloodStatusByArea(SearchLatestFloodStatusByAreaRequest) returns (SearchLatestFloodStatusByAreaResponse)

按地理区域搜索最新洪水状况。注意：返回 gauge 位于指定区域内的洪水状态，而不是例如与指定区域相交的受影响区域。但将来这项优惠可能会发生变化。

BatchGetGaugeModelsRequest

BatchGetGaugeModels 的请求。

字段
names[]

string

必需。要检索的流量计模型名称。名称格式：gaugeModels/{gauge_id}。支持的名单规模上限为 2 万。如果提供的列表包含的元素超过 20,000 个，则会失败并显示 INVALID_REQUEST 错误。

BatchGetGaugeModelsResponse

BatchGetGaugeModels 的响应。

字段
gauge_models[]

GaugeModel

所请求的指标模型。

BatchGetGaugesRequest

BatchGetGauges 的请求。

字段
names[]

string

必需。要检索的指标名称。名称格式：gauges/{gauge_id}。支持的名单大小上限为 10 万。如果提供的列表包含的元素超过 10 万个，则会失败并显示 INVALID_REQUEST 错误。

BatchGetGaugesResponse

BatchGetGauges 的响应。

字段
gauges[]

Gauge

所请求的指标。

FloodStatus

系统发布的洪水状态。表示系统针对某个区域预测的洪水状态，包含严重程度、预测变化、淹没地图等属性。详见下文说明。

字段
gauge_id

string

相应状态所针对的指标的 ID。
quality_verified

bool

如果发布此洪水状态的水位计没有模型，或者有模型但模型经过质量验证，则为 True。当此值设置为 false 时，请谨慎使用。
gauge_location

LatLng

相应状态所针对的流量计的位置。
issued_time

string

相应状态的发布时间（采用 ISO 8601 字符串格式），例如 "2023-06-17T10:34:00Z".
forecast_time_range

TimeRange

预测所针对的时间范围。
forecast_change

ForecastChange

从上次已知状态到预测的预测值变化。目前仅适用于水位模型。
forecast_trend

ForecastTrend

预测的趋势。
map_inference_type

MapInferenceType

相应地图的创建所依据的推理类型。
severity

Severity

状态的严重程度。
inundation_map_set

InundationMapSet

推断出的洪灾地图集。
source

string

负责相应指标数据的组织，例如GRDC、CWC 等
serialized_notification_polygon_id

string

序列化通知多边形的 ID，表示 Google 用于确定何时向用户发出提醒的地理区域。使用 GetSerializedPolygon 获取序列化后的多边形本身。

ForecastChange

从上次已知状态到预测值的预测值变化。目前仅适用于水位模型。

字段
value_change

ValueChange

预测的值变化。
reference_time_range

TimeRange

上次已知状态的时间范围，我们根据此范围预测值变化。例如，我们可能将参考时间范围设置为昨天，并将值变化设置为 25-30 厘米。这意味着，25-30 厘米的水位上涨幅度是与昨天的水位相比，而不是与当前的水位相比。

ValueChange

预测的值变化 - 上限和下限。

字段
lower_bound

double

预测变化量的下限（以米为单位）。如果变化介于 20 到 30 之间，则此值为 20。如果变化介于 -30 和 -20 之间，则此值为 -30。
upper_bound

double

预测变化（以米为单位）的上限。如果变化介于 20 到 30 之间，则此值为 30。如果变化介于 -30 和 -20 之间，则此值为 -20。

ForecastTrend

表示预测趋势的枚举。

枚举
FORECAST_TREND_UNSPECIFIED 默认值。此值未使用。
RISE 这表示预测值有所上升。
FALL 这表示预测值下降。
NO_CHANGE 这表示预测值没有变化。

InundationMap

一张洪灾地图。

字段
level

InundationLevel

洪灾地图的级别 - 请参阅基于 InundationMapType 的文档。
serialized_polygon_id

string

表示相应洪涝风险地图的序列化多边形的 ID。使用 GetSerializedPolygon 获取序列化后的多边形本身。

InundationLevel

表示淹没程度的枚举。

枚举
INUNDATION_LEVEL_UNSPECIFIED 默认值。此值未使用。
HIGH 请参阅基于 InundationMapType 的文档。
MEDIUM 请参阅基于 InundationMapType 的文档。
LOW 请参阅基于 InundationMapType 的文档。

InundationMapSet

一组洪灾地图。

字段
inundation_maps[]

InundationMap

洪灾地图，每个洪灾级别对应一张。
inundation_maps_time_range

TimeRange

淹没地图所指状态的时间范围。
inundation_map_type

InundationMapType

洪灾地图的类型。

InundationMapType

表示淹没地图类型的枚举。

枚举
INUNDATION_MAP_TYPE_UNSPECIFIED 默认值。此值未使用。
PROBABILITY 类型概率图。InundationLevel 表示地图概率，即发生洪灾的概率（高/中/低）。高概率多边形包含在中概率多边形内，而中概率多边形包含在低概率多边形内。
DEPTH 类型深度图。InundationLevel 表示地图深度，即每个位置的深度（高/中/低）。高深度多边形包含在中深度多边形内，中深度多边形包含在低深度多边形内。

MapInferenceType

表示地图推理类型的枚举。

枚举
MAP_INFERENCE_TYPE_UNSPECIFIED 默认值。此值未使用。
MODEL 这表示相应推理是使用模型创建的。
IMAGE_CLASSIFICATION 这表示相应推理是使用图片分类创建的。

严重程度

表示状态严重程度的枚举。

枚举
SEVERITY_UNSPECIFIED 默认值。此值未使用。
EXTREME 表示预测的极端状态。
SEVERE 这表示预测的严重状态。
ABOVE_NORMAL 这表示预测的“高于正常水平”状态。
NO_FLOODING 这表示预测不会发生洪水。
UNKNOWN 这表示我们没有足够的信息来确定严重程度。

预测

单个水位站针对多个提前期的预测。例如，预报的发布时间可能是下午 5 点，其中包含下午 6 点、7 点、8 点等的预报。

注意：部分预测范围可能早于发布时间。这种情况可能是由模型输入数据的延迟造成的。在上述示例中，问题时间可能是下午 5 点，而预测范围是下午 4 点、下午 5 点、下午 6 点等。

注意：区间的长度和区间之间的距离各不相同。以下是一些可能的范围示例：

  1. [下午 5 点 - 下午 5 点]、[下午 6 点 - 下午 6 点]、[晚上 7 点 - 晚上 7 点]

  2. [3 月 1 日中午 12 点 - 3 月 2 日中午 12 点]、[3 月 2 日中午 12 点 - 3 月 3 日中午 12 点]、[3 月 3 日中午 12 点 - 3 月 4 日中午 12 点]

字段
forecast_ranges[]

ForecastTimedValue

预测由多个“预测范围”组成，这些范围是与不同时间范围相关的不同预测值。如果范围的开始和结束时间相同，则表示这是一个时间点。
gauge_id

string

相应预测所针对的水位计的 ID。
issued_time

string

预报的发布时间 (ISO 8601)，例如“2023-06-17T10:34:00Z”。发布时间是指生成天气预报的时间。

ForecastSet

一个流量计的一组预测数据。

字段
forecasts[]

Forecast

天气预报。

ForecastTimedValue

与时间范围相关的预测值。其单位由与之关联的 GaugeModel 定义。如果开始时间和结束时间相同，则表示这是一个时间点。

字段
value

double

预测值。
forecast_start_time

string

区间的开始时间。
forecast_end_time

string

区间的结束时间。

仪表盘

指标的元数据。

字段
location

LatLng

测量仪的实际位置。
site_name

string

相应水位计所在站点的名称（英文）。这不是唯一标识符；附近位置可能存在多个具有相同站点名称的水位计。不一定提供。
source

string

负责此水位计数据的组织，例如 GRDC、CWC 等。
river

string

水位计的河流名称（英文）。不一定提供。
country_code

string

指标所在国家/地区的国家/地区代码 (ISO 3166 Alpha-2)。
gauge_id

string

指标的 ID。
quality_verified

bool

如果流量计没有模型，或者有模型且模型经过质量验证，则此字段为 true。当此值设置为 false 时，请谨慎使用。
has_model

bool

如果流量计有模型，则此字段为 true。如果表计有模型，则可以使用 GetGaugeModel 或 BatchGetGaugeModels 获取相应表计的 GaugeModel。并使用 QueryGaugeForecasts 获取其预测。

GaugeModel

指标模型的元数据。

字段
gauge_id

string

指标的 ID。
gauge_model_id

string

流量计模型的 ID。有时，指标的模型可能会发生变化，在这种情况下，我们会为新模型分配新的 ID 和新的阈值。如果新旧预测是由不同的模型生成的，请谨慎比较。
thresholds

Thresholds

水位计的阈值。
gauge_value_unit

GaugeValueUnit

指标模型的价值单位。
quality_verified

bool

相应模型是否已通过质量验证。当此值设置为 false 时，请谨慎使用。

GaugeValueUnit

可能的指标值单位。

枚举
GAUGE_VALUE_UNIT_UNSPECIFIED 默认值。此值未使用。
METERS 米。
CUBIC_METERS_PER_SECOND 立方米/秒。

GetGaugeModelRequest

GetGaugeModel 的请求。

字段
name

string

必需。要检索的流量计模型名称。名称格式：gaugeModels/{gauge_id}。

GetGaugeRequest

GetGauge 的请求。

字段
name

string

必需。要检索的指标的名称。名称格式：gauges/{gauge_id}。

GetSerializedPolygonRequest

GetSerializedPolygon 的请求。

字段
name

string

必需。要检索的序列化多边形的名称。名称格式：serializedPolygons/{polygon_id}

循环

地图上的环线。表示简单的球面多边形。它由一个顶点链组成，其中第一个顶点隐式连接到最后一个顶点。

字段
vertices[]

LatLng

必需。环路的顶点。

QueryGaugeForecastsRequest

QueryGaugeForecasts 的请求。

字段
gauge_ids[]

string

必需。指标 ID 列表。支持的列表大小上限为 500。如果提供的列表包含的元素超过 500 个，则会失败并显示 INVALID_REQUEST 错误。
issued_time_start

string

可选。最早的预报发布时间（采用 ISO 8601 格式），例如“2023-06-17T10:34:00Z”或日期字符串，例如“2023-10-13”。开始时间不能早于“2023-10-01”。默认值为一周前。
issued_time_end

string

可选。以字符串 (ISO 8601) 格式表示的最新预报发布时间，例如“2023-06-17T10:34:00Z”或日期字符串，例如“2023-10-13”。默认值为“现在”。

QueryGaugeForecastsResponse

QueryGaugeForecasts 的响应。

字段
forecasts

map<string, ForecastSet>

从水位计 ID 到预测集的映射。

QueryLatestFloodStatusByGaugeIdsRequest

QueryLatestFloodStatusByGaugeIds 的请求。

字段
gauge_ids[]

string

必需。指标 ID 列表。支持的名单规模上限为 2 万。如果提供的列表包含的元素超过 20,000 个，则会失败并显示 INVALID_REQUEST 错误。

QueryLatestFloodStatusByGaugeIdsResponse

QueryLatestFloodStatusByGaugeIds 的响应。

字段
flood_statuses[]

FloodStatus

所请求水位计的最新洪水状态。

SearchGaugesByAreaRequest

SearchGaugesByArea 的请求。

字段
page_size

int32

可选。要返回的指标数量上限。服务返回的值可能小于此值。如果未指定，则最多返回 50,000 个指标。最大值为 50,000；大于 50,000 的值会强制转换为 50,000。
page_token

string

可选。从之前的 SearchGauges 调用接收的页面令牌。利用其进行后续页面检索。进行分页时，提供给 SearchGauges 的所有其他参数必须与提供页面令牌的调用相一致。

联合字段 search_by。

search_by 只能是下列其中一项：
region_code

string

按区域代码搜索某个区域内的所有水位计。使用 https://cldr.unicode.org/（列表 https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)）。
loop

Loop

搜索环内的所有测量仪（一个简单的球面多边形，请参阅 Loop）。
include_non_quality_verified

bool

可选。在结果仪表中包含未经过质量验证的指标。请谨慎使用。默认值为 false。
include_gauges_without_hydro_model

bool

可选。纳入结果中没有 Google 内部水文模型的流量计。默认值为 false。

SearchGaugesByAreaResponse

SearchGaugesByArea 的响应。

字段
gauges[]

Gauge

所请求区域内的水位计。
next_page_token

string

可选。可作为 page_token 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

SearchLatestFloodStatusByAreaRequest

SearchLatestFloodStatusByArea 的请求。

字段
page_token

string

可选。从之前的 SearchLatestFloodStatusByArea 调用接收的页面令牌。利用其进行后续页面检索。进行分页时，提供给 SearchLatestFloodStatusByArea 的所有其他参数必须与提供页面令牌的调用相一致。
page_size

int32

可选。要返回的泛洪状态数量上限。服务返回的值可能小于此值。如果未指定，则最多返回 20,000 个洪泛状态。最大值为 20,000；大于 20,000 的值会强制转换为 20,000。

联合字段 area_type。

area_type 只能是下列其中一项：
region_code

string

用于查询洪水状态的区域。使用 CLDR，例如 'US'。
loop

Loop

用于查询 Flood 状态的循环。
include_non_quality_verified

bool

可选。在结果仪表中包含未经过质量验证的指标。请谨慎使用。默认值为 false。

SearchLatestFloodStatusByAreaResponse

SearchLatestFloodStatusByArea 的响应。

字段
flood_statuses[]

FloodStatus

所请求区域的最新洪水状态。目前，此设置取决于仪表的位置，但将来可能会发生变化。
next_page_token

string

可选。可作为 page_token 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

SerializedPolygon

序列化多边形。

字段
polygon_id

string

多边形的 ID。
kml

string

多边形的 KML 字符串表示形式。

阈值

水位计模型的阈值。

字段
warning_level

double

警告级别。
danger_level

double

危险水位。
extreme_danger_level

double

极度危险水位。不一定提供。

TimeRange

时间范围。

字段
start

string

时间范围的开始时间。以 ISO 8601 格式表示，例如 "2023-06-17T10:34:00Z".
end

string

时间范围的结束时间。以 ISO 8601 格式表示，例如 "2023-06-17T10:34:00Z".