נקודת הקצה
publicAlerts
מספקת פרטים על התראות ספציפיות לגבי אירועי מזג אוויר שהונפקו על ידי סוכנויות לאומיות ובינלאומיות מוסמכות. ההתראות האלה מספקות מידע חיוני, שיכול להציל חיים.
נקודת הקצה מחזירה התראות על מזג אוויר שמתרחשות בזמן אמת בקו רוחב ובקו אורך נתונים. אירועי מזג האוויר הנתמכים כוללים את:
- משקעים: גשם, שלג, ברד, בצורות ועוד
- טמפרטורות קיצוניות: קור, חום, הקפאה, כפור, צינת רוח ולחות
- אירועים שקשורים לרוח ולסערה: סופות שלגים, הוריקנים, טורנדו, סופות טרופיות, סופות רעמים ועוד
- פגיעה בראות: ערפל, סופות אבק ומשבי שלגים
- סכנות שקשורות למים: שיטפונות, צונאמי, גלי סערה, סכנות באזורי חוף ועוד
- אירועים גיאופיזיים וגיאולוגיים: רעידות אדמה, מפולות ופעילות געשית
- אירועי שריפות: שריפות יער, מזג אוויר שגורם לשריפות ועוד
רשימה מלאה של אירועי מזג האוויר הנתמכים מופיעה במאמר סוגי אירועי מזג האוויר.
יכול להיות שההתראות יכללו תיאורים מותאמים לשפה המקומית, ויכול להיות שלא, בהתאם למה שזמין ממקור הנתונים. בגלל מגבלות על מקור הנתונים, המידע מוצג כמו שהוא (תוכן גולמי). מידע נוסף על מקורות של התראות על מזג האוויר זמין במאמר מקורות נתונים.
ה-API מחזיר את המידע הבא לגבי התראת מזג אוויר מסוימת:
- סוג אירוע מזג האוויר שמשויך להתראה
- רשימה של אזורים מושפעים, יחד עם קואורדינטות שמגדירות את הגבולות הגיאוגרפיים של האזורים האלה
- סיכום במשפט אחד של אירוע מזג האוויר
- רמות החומרה, הוודאות והדחיפות
- תיאור של הוראות לפעולה לקהל היעד
- המלצות בנושא בטיחות
- שעת ההתחלה ושעת הסיום של ההתראה
- השם והאתר של רשות הפרסום
APIs Explorer מאפשר לכם לשלוח בקשות בזמן אמת כדי להכיר את ה-API ואת האפשרויות שלו:
מידע על בקשות להתרעות על מזג האוויר
כדי לבקש מידע על התראות מזג אוויר, שולחים בקשת GET של HTTP אל:
https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE&languageCode=LANGUAGE_CODE
כוללים את הקואורדינטות של קו הרוחב וקו האורך של המיקום בפרמטרים של כתובת ה-URL של הבקשה.
מידע על תשובות שקשורות להתראות על מזג האוויר
התשובה של Weather API כוללת את השדות הבאים בגוף התשובה:
| שדה | סוג | תיאור | נדרש או אופציונלי |
|---|---|---|---|
alertId |
מחרוזת | מזהה ההתראה. אפשר למצוא את המידע הזה גם באתר של ספק הנתונים. | חובה |
alertTitle |
מחרוזת | שם ההתראה, שמתאר את אירוע מזג האוויר. הערה: זו המחרוזת היחידה שמתורגמת כשפרמטר של קוד שפה נכלל בבקשה. |
חובה |
eventType |
ספירה | סוג אירוע מזג האוויר שמשויך להתראה. רשימה מלאה של אירועי מזג האוויר הנתמכים זמינה במאמר סוגי אירועי מזג האוויר. |
חובה |
areaName |
מחרוזת | שם האזור הגיאוגרפי שההתראה רלוונטית לגביו, כולל המיקום המבוקש. | חובה |
polygon |
מחרוזת | קואורדינטות שמגדירות אזור סגור רב-ממדי של ההתראה. | אופציונלי |
description |
מחרוזת | ביטוי קצר שמסכם את תיאור האירוע בשפה שצוינה (לדוגמה, "אזהרה על טורנדו"). | אופציונלי |
severity |
ספירה | רמת החומרה של ההתראה:
|
אופציונלי |
certainty |
ספירה | רמת הוודאות של ההתראה:
|
אופציונלי |
urgency |
ספירה | רמת הדחיפות של ההתראה:
|
אופציונלי |
instruction |
מחרוזת | תיאור של הוראות לפעולה רספונסיבית לקהל היעד. | אופציונלי |
safetyRecommendations |
מחרוזת | המלצות בנושא בטיחות שמבוססות על קודים של רשויות ציבוריות. כולל הנחיות ברמה העליונה וטקסט משני עם מידע נוסף. | אופציונלי |
timezoneOffset |
מחרוזת | ההפרש מאזור הזמן של האירוע, בפורמט +/-HH:MM. | חובה |
startTime |
DateTime | התאריך והשעה של ראשית זמן יוניקס (Unix epoch) שבהם המידע בהודעת ההתראה נכנס לתוקף (לפי שעון UTC). | אופציונלי |
expirationTime |
DateTime | התאריך והשעה של תקופת Epoch (זמן UTC) שבהם צפוי להסתיים ההתראה. יכול להיות שהערך יהיה null לאירועים שנמשכים ללא הגבלת זמן. במקרה כזה, בכותרת יצוין שהאירוע "בתוקף". | אופציונלי |
dataSource |
ספירה | פרטי הרשות, כולל שם אתר החדשות, השם וכתובת ה-URL. | חובה |
regionCode |
ספירה | קוד האזור של המיקום המבוקש. | אופציונלי |
מקורות נתונים
נקודת הקצה של התראות מזג האוויר מחזירה נתונים שפורסמו על ידי הספקים שמפורטים בטבלה הבאה. על סמך הקואורדינטות של קו הרוחב וקו האורך שצוינו בבקשה, גוף התגובה מציג נתונים מהרשות המקומית המתאימה.
הספקים שכלולים בפיד פועלים בהתאם להנחיות של Google בנושא Public Alerts. Google עשויה לעדכן את רשימת הספקים בכל שלב.
שיוך (Attribution)
בכל התצוגות שבהן הנתונים מוצגים, האפליקציה של הלקוח חייבת לכלול שיוך למקור המקורי באמצעות השדה dataSource:
"dataSource": {
"publisher": "NOAA",
"name": "National Weather Service",
"authorityUri": "https://www.weather.gov/"
}
השיוך צריך לכלול את השם המלא של מקור הנתונים (כפי שצוין בשדה name) וקישור היפרטקסט למקור הנתונים באמצעות כתובת ה-URL שצוינה בשדה authorityUri (לדוגמה, National Weather Service).
סוגים של אירועי מזג אוויר
אלה סוגי אירועי מזג האוויר שנתמכים:
| סוגים של אירועי מזג אוויר | |
|---|---|
ACID_RAINAVALANCHEBLIZZARDBLOWING_SNOWCOASTAL_FLOODCOASTAL_HAZARDCOLDCYCLONEDROUGHTEXTRATROPICAL_CYCLONEFIRE_WEATHERFLASH_FLOODFLOODFOGFREEZINGFREEZING_AIR_TEMPERATUREFREEZING_DRIZZLEFREEZING_RAINFROSTGALEGLAZEHAILHAZARDOUS_SEASHEATHUMIDITYHURRICANEICE_STORMLAKE_EFFECT_SNOWMONSOONMUDDY_FLOODOUTFLOWRAIN
|
RIVER_FLOODINGSEVERE_THUNDERSTORM_WARNINGSNOWSNOWSQUALLSTORMSTORM_SURGETHUNDERTHUNDERSTORMTORNADOTORNADO_WARNINGTROPICAL_CYCLONETROPICAL_CYCLONE_WARNINGS_AND_WATCHESTROPICAL_DISTURBANCETROPICAL_STORMTYPHOONWINDWIND_CHILLWIND_WAVEWINTER_STORMWILDFIREBUSHFIREFIRELANDSLIDEEARTHQUAKEDUST_STORMAFTERSHOCKTSUNAMIVOLCANIC_ASHVOLCANIC_ERUPTIONRADIATION |
התנהגות התרגום של התשובה
Google מספקת תרגומים רק לשדה alertTitle. יכול להיות שגם שדות אחרים כמו eventType, areaName, instruction ו-safetyRecommendations יתורגמו, בהתאם לתמיכה בשפה של מקור הנתונים המקורי. עם זאת, Google לא יכולה לספק תרגומים עצמאיים לשדות האלה.
בהתאם לפרמטר languageCode שכלול בבקשה, אלה ההתנהגויות הצפויות בשדה alertTitle:
- נתמך
languageCode: אםlanguageCodeהמבוקש מסופק ונתמך, התשובה מוחזרת בשפה המבוקשת. - לא נתמך
languageCode: במקרים שבהם השפה המבוקשתlanguageCodeלא נתמכת ולא ניתן למצוא חלופה קרובה, נקודת הקצה מחזירה את התגובה באנגלית כברירת מחדל. - לא צוין
languageCode: נקודת הקצה מחזירה את התשובה באנגלית כברירת מחדל.
דוגמה לבקשה של התראה בנוגע למזג האוויר
בדוגמה הבאה מוצגת בקשה לקבלת מידע על התראות מזג אוויר בעיירה בקרוליינה הצפונית:
curl -X GET "https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=35.824635 &location.longitude=-78.3168047 &languageCode=en"
גוף התגובה הוא:
{ "weatherAlerts": [ { "alertId": "urn:oid:2.49.0.1.840.0.2416b1b5a6f51d29ef4b94948328dca303fbbb5c.001.1", "alertTitle": { "text": "Flash Flood Warning", "languageCode": "en" }, "eventType": "FLASH_FLOOD", "areaName": "Franklin, NC; Johnston, NC; Nash, NC; Wake, NC", "polygon": "{\"type\":\"Polygon\",\"coordinates\":[[[-78.450000,35.820000],[-78.410000,35.730000],[-78.280000,35.660000],[-78.180000,35.740000],[-77.840000,36.150000],[-77.890000,36.140000],[-77.900000,36.160000],[-77.920000,36.170000], [-77.930000,36.190000], [-77.940000,36.190000],[-77.950000,36.180000],[-77.970000,36.190000],[-77.970000,36.180000], [-77.980000,36.180000],[-78.010000,36.210000],[-78.040000,36.210000],[-78.110000,36.210000],[-78.130000,36.230000], [-78.350000,35.940000],[-78.450000,35.820000]]]}", "description": "FFWRAH\n\nThe National Weather Service in Raleigh has issued a\n\n* Flash Flood Warning for... \nEastern Franklin County in central North Carolina...\nNorth Central Johnston County in central North Carolina... \nWestern Nash County in central North Carolina...\nEast Central Wake County in central North Carolina... \n\n* Until 530 PM EDT.\n\n* At 224 PM EDT, local law enforcement reported flash flooding in\nSpring Hope. Between 3 and 5 inches of rain have fallen. \nAdditional rainfall amounts of 1 to 3 inches are possible in the\nwarned area.\n\nHAZARD...Life threatening flash flooding. Heavy rain producing\nflash flooding.\n\nSOURCE...Law enforcement reported.\n\nIMPACT...Life threatening flash flooding of creeks and streams,\nurban areas, highways, streets and underpasses.\n\n* Some locations that will experience flash flooding include... \nZebulon, Bunn, Wendell, Spring Hope, Middlesex, Castalia,\nCenterville, Pilot, Emit and Aventon.", "severity": "SEVERE", "certainty": "LIKELY", "urgency": "IMMEDIATE", "instruction": [ "Turn around, don't drown when encountering flooded roads. Most flood\ndeaths occur in vehicles." ], "safetyRecommendations": [ { "directive": "Build an emergency kit and make a family communications plan.", "subtext": "Follow the instructions at http://www.ready.gov/build-a-kit for building an emergency kit and http://www.ready.gov/make-a-plan for a family communications plan." }, { "directive": "Be aware that flash flooding can occur. ", "subtext": "If there is any possibility of a flash flood, move immediately to higher ground. Do not wait for instructions to move." }, ... ], "timezoneOffset": "-14400s", "startTime": "2025-08-06T18:24:00Z", "expirationTime": "2025-08-06T21:30:00Z", "dataSource": { "publisher": "NOAA", "name": "National Weather Service", "authorityUri": "https://www.weather.gov/" } } ], "regionCode": "US" }
רוצה לנסות?
APIs Explorer מאפשר לכם לשלוח בקשות לדוגמה כדי להכיר את ה-API ואת האפשרויות שלו.
בצד שמאל של הדף, לוחצים על סמל ה-API api.
אפשר לערוך את פרמטרים של הבקשה.
לוחצים על הלחצן Execute (הפעלה). בתיבת הדו-שיח, בוחרים את החשבון שבו רוצים להשתמש כדי לשלוח את הבקשה.
בחלונית APIs Explorer, לוחצים על סמל המסך המלא מסך מלא כדי להרחיב את החלון של APIs Explorer.