نقطه پایانی
publicAlerts
جزئیات هشدارهای رویدادهای آب‌وهوایی خاص را که توسط
سازمان‌های معتبر ملی و بین‌المللی صادر شده‌اند ارائه می‌دهد. این هشدارها اطلاعات حیاتی و
احتمالاً نجات‌بخش ارائه می‌دهند.
نقطه پایانی هشدارهای آب‌وهوایی را که در زمان واقعی برای عرض جغرافیایی و طول جغرافیایی مشخصی رخ می‌دهند برمی‌گرداند. رویدادهای آب‌وهوایی پشتیبانی‌شده شامل موارد زیر است:
- بارش: باران، برف، تگرگ، خشکسالی، و غیره
- دمای شدید: سرما، گرما، یخ‌زدگی، سرمازدگی، سرمای باد، و رطوبت
- رویدادهای باد و توفان: کولاک، توفند، گردباد، توفان حاره‌ای، توفان تندری، و غیره
- اختلالات دید: مه، طوفان گردوغبار، و کولاک برف
- خطرات مرتبط با آب: سیل، سونامی، خیزاب، خطرات ساحلی، و غیره
- رویدادهای ژئوفیزیکی و زمین‌شناسی: زمین‌لرزه، رانش زمین، و فعالیت‌های آتشفشانی
- حوادث آتش‌سوزی: آتش‌سوزی جنگل‌ها، آب‌وهوای آتش‌سوزی، و غیره
برای فهرست کامل رویدادهای آب‌وهوایی پشتیبانی‌شده، انواع رویدادهای آب‌وهوایی را ببینید.
هشدارها ممکن است حاوی شرح‌های بومی‌سازی‌شده باشند یا نباشند، بسته به اینکه چه چیزی از منبع داده دردسترس است. به‌دلیل محدودیت‌های منبع داده، اطلاعات همان‌گونه که هست (محتوای خام) ارائه می‌شود. برای اطلاعات بیشتر درباره منابع هشدار آب‌وهوا، منابع داده را ببینید.
این API اطلاعات زیر را برای هشدار آب‌وهوای معین برمی‌گرداند:
- نوع رویداد آب‌وهوایی مرتبط با هشدار
- فهرست مناطق تحت‌تأثیر به‌همراه مختصات تعریف‌کننده مرزهای جغرافیایی آن مناطق
- خلاصه یک‌جمله‌ای رویداد آب‌وهوایی
- سطوح شدت، قطعیت، و فوریت
- شرحی از دستورالعمل‌های اقدام-توصیه برای مخاطب هدف
- توصیه‌های ایمنی
- زمان‌های شروع و پایان هشدار
- نام و وب‌سایت مرجع انتشار
APIs Explorer به شما امکان می‌دهد درخواست‌های مستقیم ارسال کنید تا بتوانید با «میانای برنامه‌سازی کاربردی» و گزینه‌های آن آشنا شوید:
درباره درخواست‌های هشدار آب‌وهوا
برای درخواست اطلاعات هشدار آب‌وهوایی، درخواست HTTP GET را به این نشانی ارسال کنید:
https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE&languageCode=LANGUAGE_CODE
مختصات طول و عرض جغرافیایی مکان را در پارامترهای نشانی وب درخواستتان بگنجانید.
درباره پاسخ‌های هشدار آب‌وهوا
«میانای برنامه‌سازی کاربردی آب‌وهوا» فیلدهای زیر را در بدنه پاسخ برمی‌گرداند:
| فیلد | نوع | شرح | ضروری یا اختیاری |
|---|---|---|---|
alertId |
رشته | شناسه هشدار. این اطلاعات را در وب‌سایت ارائه‌دهنده داده نیز می‌توانید پیدا کنید. | الزامی |
alertTitle |
رشته | عنوان هشدار که رویداد آب‌وهوایی را توصیف می‌کند. توجه: این تنها رشته‌ای است که وقتی پارامتر کد زبان در درخواست گنجانده می‌شود ترجمه می‌شود. |
الزامی |
eventType |
شمارشی | نوع رویداد آب‌وهوایی مرتبط با هشدار. برای مشاهده فهرست کامل رویدادهای آب‌وهوایی پشتیبانی‌شده، به انواع رویدادهای آب‌وهوایی مراجعه کنید. |
الزامی |
areaName |
رشته | نام منطقه جغرافیایی تحت‌تأثیر هشدار، که شامل مکان درخواستی می‌شود. | الزامی |
polygon |
رشته | مختصاتی که ناحیه ابعادی بسته هشدار را تعریف می‌کند. | اختیاری |
description |
رشته | عبارت کوتاهی که شرح رویداد را به زبان مشخص‌شده خلاصه می‌کند (برای مثال، «هشدار گردباد»). | اختیاری |
severity |
شمارشی | سطح شدت هشدار:
|
اختیاری |
certainty |
شمارشی | سطح اطمینان برای هشدار:
|
اختیاری |
urgency |
شمارشی | سطح فوریت هشدار:
|
اختیاری |
instruction |
رشته | شرح دستورالعمل‌های کنش پاسخ‌گو برای مخاطب هدف. | اختیاری |
safetyRecommendations |
رشته | توصیه‌های ایمنی براساس کدهای مقامات دولتی. شامل دستورات سطح بالا و زیرمتن با اطلاعات اضافی است. | اختیاری |
timezoneOffset |
رشته | انحراف منطقه زمانی رویداد، در قالب +/-HH:MM. | الزامی |
startTime |
DateTime | تاریخ و زمان مؤثر Epoch (زمان UTC) اطلاعات در پیام هشدار. | اختیاری |
expirationTime |
DateTime | تاریخ و زمان Epoch (زمان UTC) که انتظار می‌رود هشدار پایان یابد. ممکن است برای رویدادهای نامحدود طولانی تهی باشد، در این صورت عنوان نشان می‌دهد که رویداد «در جریان» است. | اختیاری |
dataSource |
شمارشی | جزئیات مرجع شامل ناشر، نام، و نشانی وب. | الزامی |
regionCode |
شمارشی | کد منطقه مکانی که درخواست شده است. | اختیاری |
منابع داده‌ها
نقطه پایانی هشدارهای آب‌وهوا داده‌های منتشرشده توسط ارائه‌دهندگان فهرست‌شده در جدول زیر را برمی‌گرداند. براساس مختصات طول و عرض جغرافیایی ارائه‌شده در درخواست، بدنه پاسخ داده‌های مربوط به مرجع محلی مناسب را نمایش می‌دهد.
ارائه‌دهندگان موجود در فید از رهنمودهای هشدارهای عمومی Google پیروی می‌کنند. Google ممکن است فهرست ارائه‌دهندگان را در هرزمانی به‌روز کند.
اِسناد
در همه نمایشگرهایی که داده‌ها ارائه می‌شود، برنامه مشتری باید
بااستفاده از فیلد dataSource، منبع اصلی را ذکر کند:
"dataSource": {
"publisher": "NOAA",
"name": "National Weather Service",
"authorityUri": "https://www.weather.gov/"
}
ذکر منبع باید شامل نام کامل منبع داده (همان‌گونه که در فیلد name ارائه شده است) و پیوند به منبع داده بااستفاده از نشانی وب ارائه‌شده در فیلد authorityUri (برای نمونه، «خدمات ملی آب‌وهوا») باشد.
انواع رویدادهای آب‌وهوایی
انواع رویدادهای آب‌وهوایی زیر پشتیبانی می‌شوند:
| انواع رویدادهای آب‌وهوایی | |
|---|---|
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" }
امتحان کنید!
«کاوشگر میاناهای برنامه‌سازی کاربردی» به شما امکان می‌دهد درخواست‌های نمونه‌ای ایجاد کنید تا بتوانید با «میانای برنامه‌سازی کاربردی» و گزینه‌های «میانای برنامه‌سازی کاربردی» آشنا شوید.
نماد API api را در سمت راست صفحه انتخاب کنید.
درصورت تمایل، پارامترهای درخواست را ویرایش کنید.
دکمه اجرا را انتخاب کنید. در کادر گفتگو، حسابی را که می‌خواهید برای درخواست استفاده کنید انتخاب کنید.
در پانل «کاوشگر API»، نماد تمام‌صفحه تمام‌صفحه را انتخاب کنید تا پنجره «کاوشگر API» ازهم باز شود.