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)

依地理區域搜尋最新淹水狀況。注意：系統會傳回水位計位於指定區域內的洪水狀態，而非與指定區域相交的受影響區域。日後可能會有變動。

BatchGetGaugeModelsRequest

BatchGetGaugeModels 的要求。

欄位
names[]

string

必要欄位。要擷取的量表模型名稱。名稱格式：gaugeModels/{gauge_id}。支援的清單大小上限為 20,000。如果提供的清單超過 20,000 個項目，系統會傳回 INVALID_REQUEST 錯誤。

BatchGetGaugeModelsResponse

BatchGetGaugeModels 的回應。

欄位
gauge_models[]

GaugeModel

要求的量規模型。

BatchGetGaugesRequest

BatchGetGauges 的要求。

欄位
names[]

string

必要欄位。要擷取的計量表名稱。名稱格式：gauges/{gauge_id}。支援的清單大小上限為 100,000。如果提供的清單超過 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 公分。也就是說，系統會比較水位與昨天的水位，而非與現在的水位。

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. [5pm - 5pm]、[6pm - 6pm]、[7pm - 7pm]

  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

此測量儀器所在網站的名稱 (英文)。這不是專屬 ID，附近地點可能有多個名稱相同的測量儀。不一定會顯示。
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 和門檻可能會不時變更，屆時我們會為新模型指派新的 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 清單。支援的清單大小上限為 20,000。如果提供的清單超過 20,000 個項目，系統會傳回 INVALID_REQUEST 錯誤。

QueryLatestFloodStatusByGaugeIdsResponse

QueryLatestFloodStatusByGaugeIds 的回應。

欄位
flood_statuses[]

FloodStatus

所要求水位計的最新洪水狀態。

SearchGaugesByAreaRequest

SearchGaugesByArea 的要求。

欄位
page_size

int32

(選用步驟) 要傳回的指標數量上限。服務傳回的產品數量可能會少於這個值。如未指定，最多將傳回 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。

聯集欄位 area_type。

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

string

要查詢洪災狀態的區域。使用 CLDR，例如 'US'。
loop

Loop

查詢洪水狀態的迴圈。
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".