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)

קבלת פוליגון שעבר סריאליזציה. המזהים של המשאבים האלה יופיעו בתגובות אחרות של ה-API, ותוכלו להשתמש בהם כאן. לדוגמה, ראו InundationMap ב-FloodStatus.
QueryGaugeForecasts

rpc QueryGaugeForecasts(QueryGaugeForecastsRequest) returns (QueryGaugeForecastsResponse)

תחזיות של מדדי שאילתות.
QueryLatestFloodStatusByGaugeIds

rpc QueryLatestFloodStatusByGaugeIds(QueryLatestFloodStatusByGaugeIdsRequest) returns (QueryLatestFloodStatusByGaugeIdsResponse)

שאילתה לגבי הסטטוס העדכני של שיטפון לפי מזהי מדיד.
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. אם הרשימה גדולה מ-100,000, הפעולה תיכשל ותוצג השגיאה INVALID_REQUEST.

BatchGetGaugesResponse

התשובה של BatchGetGauges.

שדות
gauges[]

Gauge

המדדים המבוקשים.

FloodStatus

סטטוס שיטפון שהונפק על ידי המערכת. מייצג את סטטוס ההצפה שחזתה המערכת באזור מסוים, עם מאפיינים כמו חומרה, שינוי בתחזית, מפות הצפה ועוד. המידע על הסיבות האפשריות מפורט כאן.

שדות
gauge_id

string

המזהה של המד שעבורו הונפק הסטטוס הזה.
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

מזהה של מצולע ההתראה הסדרתי, שמייצג את האזור הגיאוגרפי ש-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

סוג enum שמייצג את המגמה של התחזית.

טיפוסים בני מנייה (enum)
FORECAST_TREND_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
RISE ההודעה הזו מצביעה על עלייה בערך הצפוי.
FALL ההודעה הזו מצביעה על ירידה בערך הצפוי.
NO_CHANGE המשמעות היא שלא חל שינוי בערך התחזית.

InundationMap

מפת שיטפונות אחת.

שדות
level

InundationLevel

רמת מפת ההצפות – אפשר לעיין במסמכים לפי InundationMapType.
serialized_polygon_id

string

מזהה של המצולע שעבר סריאליזציה ומייצג את מפת הסיכון להצפה הזו. משתמשים ב-GetSerializedPolygon כדי לקבל את הפוליגון עצמו בצורה סדרתית.

InundationLevel

סוג enum שמייצג רמות של הצפה.

טיפוסים בני מנייה (enum)
INUNDATION_LEVEL_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
HIGH אפשר לעיין בתיעוד על סמך InundationMapType.
MEDIUM אפשר לעיין בתיעוד על סמך InundationMapType.
LOW אפשר לעיין בתיעוד על סמך InundationMapType.

InundationMapSet

קבוצה של מפות שיטפונות.

שדות
inundation_maps[]

InundationMap

מפות של שיטפונות, אחת לכל רמת שיטפון.
inundation_maps_time_range

TimeRange

טווח הזמן של המצב שאליו מתייחסות מפות ההצפה.
inundation_map_type

InundationMapType

סוג מפת השיטפונות.

InundationMapType

סוג enum שמייצג את סוג מפת השיטפונות.

טיפוסים בני מנייה (enum)
INUNDATION_MAP_TYPE_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
PROBABILITY מפה של הסתברות לסוג. הערך InundationLevel מייצג את הסבירות להצפה במפה – סבירות גבוהה, בינונית או נמוכה להצפה. המצולע של ההסתברות הגבוהה מוכל במצולע של ההסתברות הבינונית, והמצולע של ההסתברות הבינונית מוכל במצולע של ההסתברות הנמוכה.
DEPTH מפה של עומק הסוג. המאפיין InundationLevel מייצג את העומק במפה – עומק גבוה, בינוני או נמוך לכל מיקום. המצולע עם העומק הגבוה נמצא בתוך המצולע עם העומק הבינוני, והמצולע עם העומק הבינוני נמצא בתוך המצולע עם העומק הנמוך.

MapInferenceType

סוג enum שמייצג סוגים של מסקנות לגבי מפות.

טיפוסים בני מנייה (enum)
MAP_INFERENCE_TYPE_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
MODEL הסימון הזה מציין שההסקה הזו נוצרה באמצעות מודל.
IMAGE_CLASSIFICATION המשמעות היא שההסקה הזו נוצרה באמצעות סיווג תמונות.

מידת החומרה

סוג enum שמייצג את חומרת הסטטוס.

טיפוסים בני מנייה (enum)
SEVERITY_UNSPECIFIED ערך ברירת המחדל. הערך הזה לא בשימוש.
EXTREME ההודעה הזו מצביעה על סטטוס קיצוני צפוי.
SEVERE המשמעות היא שהסטטוס החמור צפוי.
ABOVE_NORMAL המשמעות היא שהסטטוס הצפוי הוא מעל הנורמה.
NO_FLOODING ההודעה הזו מציינת שאין תחזית לשיטפונות.
UNKNOWN המשמעות היא שאין לנו מספיק מידע כדי לקבוע את חומרת הבעיה.

תחזית

תחזית של מדד יחיד לכמה זמני אספקה. לדוגמה, יכול להיות שזמן הבעיה בתחזית הוא 17:00, והיא כוללת תחזיות לשעות 18:00, 19:00, 20:00 וכו'.

הערה: יכול להיות שחלק מטווח התחזית יהיה מוקדם יותר מהשעה שבה התחזית פורסמה. לדוגמה, יכול להיות שהנתונים שמוזנים למודל לא מעודכנים. בדוגמה שלמעלה, יכול להיות ששעת הבעיה היא 17:00, וטווח התחזית הוא 16:00, 17:00, 18:00 וכו'.

הערה: אורך הטווחים והמרחק ביניהם משתנים. דוגמאות לטווחים אפשריים:

  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]

שדות
forecast_ranges[]

ForecastTimedValue

תחזית מורכבת מכמה 'טווחים של תחזיות', שהם ערכי תחזית שונים שמתייחסים לטווחים שונים של זמן. אם ההתחלה והסיום של טווח שווים, המשמעות היא שמדובר בנקודת זמן.
gauge_id

string

המזהה של מדד ההתקדמות שאליו מתייחסת התחזית הזו.
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

המזהה של המד.
quality_verified

bool

השדה הזה מחזיר True אם למדד אין מודל, או אם יש לו מודל והמודל אומת מבחינת איכות. חשוב להיזהר כשמגדירים את הערך הזה כ-false.
has_model

bool

הערך בשדה הזה הוא true אם למדד יש מודל. אם יש למדד מודל, אפשר לקבל את GaugeModel של המדד הזה באמצעות GetGaugeModel או BatchGetGaugeModels. וגם לקבל את התחזיות שלו באמצעות QueryGaugeForecasts.

GaugeModel

מטא-נתונים של מודל של מד.

שדות
gauge_id

string

המזהה של המד.
gauge_model_id

string

המזהה של המודל של מדד השימוש. יכול להיות שמדי פעם המודל של מדד מסוים ישתנה, ובמקרה כזה נשייך מזהה חדש וערכי סף חדשים למודל החדש. אם התחזיות הישנות והחדשות נוצרו על ידי מודלים שונים, צריך להיזהר כשמשווים ביניהן.
thresholds

Thresholds

ערכי הסף של המד.
gauge_value_unit

GaugeValueUnit

יחידת הערך של המודל של המדד.
quality_verified

bool

האם המודל הזה אומת מבחינת איכות. חשוב להיזהר כשמגדירים את הערך הזה כ-false.

GaugeValueUnit

יחידות אפשריות של ערכי מדדים.

טיפוסים בני מנייה (enum)
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

חובה. רשימה של מזהי מדדים. גודל הרשימה הנתמך מוגבל ל-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>

מפה ממזהה מדד לקבוצת תחזיות.

QueryLatestFloodStatusByGaugeIdsRequest

הבקשה של QueryLatestFloodStatusByGaugeIds.

שדות
gauge_ids[]

string

חובה. רשימה של מזהי מדדים. גודל הרשימה הנתמך מוגבל ל-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

המזהה של הפוליגון.
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".