دریافت هشدارهای آب‌وهوا

نقطه پایانی 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

مختصات طول و عرض جغرافیایی مکان را در پارامترهای نشانی وب درخواستتان بگنجانید.

درباره پاسخ‌های هشدار آب‌وهوا

Weather API فیلدهای زیر را در بدنه پاسخ برمی‌گرداند:

فیلد نوع شرح ضروری یا اختیاری
alertId رشته شناسه هشدار. این اطلاعات را در وب‌سایت ارائه‌دهنده داده نیز می‌توانید پیدا کنید. الزامی
alertTitle رشته عنوان هشدار که رویداد آب‌وهوایی را توصیف می‌کند.

توجه: این تنها رشته‌ای است که وقتی پارامتر کد زبان در درخواست گنجانده می‌شود ترجمه می‌شود.
الزامی
eventType شمارشی نوع رویداد آب‌وهوایی مرتبط با هشدار.

برای مشاهده فهرست کامل رویدادهای آب‌وهوایی پشتیبانی‌شده، به انواع رویدادهای آب‌وهوایی مراجعه کنید.
الزامی
areaName رشته نام منطقه جغرافیایی تحت‌تأثیر هشدار که شامل مکان درخواستی است. الزامی
polygon رشته مختصاتی که ناحیه ابعادی بسته هشدار را تعریف می‌کند. اختیاری
description رشته عبارت کوتاهی که شرح رویداد را به زبان مشخص‌شده خلاصه می‌کند (برای مثال، «هشدار گردباد»). اختیاری
severity شمارشی سطح شدت هشدار:
  • بسیار شدید: تهدید فوق‌العاده جانی یا مالی
  • شدید: تهدید جدی جانی یا مالی
  • متوسط: خطر احتمالی جانی یا مالی
  • جزئی: تهدید جانی یا مالی شناخته‌شده وجود ندارد یا بسیار کم است
  • نامشخص: شدت نامشخص است
اختیاری
certainty شمارشی سطح اطمینان برای هشدار:
  • مشاهده‌شده: مشخص شده است که رخ داده یا درحال وقوع است
  • بسیار محتمل: بسیار محتمل است که رخ داده باشد یا درحال وقوع باشد
  • احتمالی: احتمال (p > ~50%) وقوع یا تداوم وجود دارد
  • ممکن: ممکن است اما احتمال اینکه رخ داده باشد یا درحال وقوع باشد کم است (p <= ~50%)
  • بعید: انتظار نمی‌رود رخ دهد (p ~ 0)
  • نامشخص: قطعیت نامشخص است
اختیاری
urgency شمارشی سطح فوریت هشدار:
  • فوری: اقدام واکنشی باید فوراً انجام شود
  • انتظار می‌رود: اقدام واکنشی باید به‌زودی (ظرف یک ساعت آینده) انجام شود
  • آینده: اقدام واکنشی باید در آینده نزدیک انجام شود
  • گذشته: دیگر نیازی به اقدام واکنشی نیست
  • نامشخص: فوریت نامشخص
اختیاری
instruction رشته شرح دستورالعمل‌های اقدام واکنشی برای مخاطب هدف. اختیاری
safetyRecommendations رشته توصیه‌های ایمنی براساس کدهای مراجع عمومی. شامل دستورالعمل‌های سطح بالا و زیرمتن با اطلاعات بیشتر است. اختیاری
timezoneOffset رشته تفاوت منطقه زمانی رویداد، در قالب +/-HH:MM. الزامی
startTime DateTime تاریخ و زمان مؤثر Epoch (زمان UTC) اطلاعات موجود در پیام هشدار. اختیاری
expirationTime DateTime تاریخ و زمان Epoch (زمان UTC) که انتظار می‌رود هشدار به‌پایان برسد. ممکن است برای رویدادهای طولانی نامحدود، مقدار آن null باشد که در این صورت عنوان نشان می‌دهد که رویداد «در حال اجرا» است. اختیاری
dataSource شمارشی جزئیات مرجع شامل ناشر، نام، و نشانی وب. الزامی
regionCode شمارشی کد منطقه مکانی که درخواست شده است. اختیاری

منابع داده‌ها

نقطه پایانی هشدارهای آب‌وهوا داده‌های منتشرشده توسط ارائه‌دهندگان فهرست‌شده در جدول زیر را برمی‌گرداند. براساس مختصات طول و عرض جغرافیایی ارائه‌شده در درخواست، بدنه پاسخ داده‌های مربوط به مرجع محلی مناسب را نمایش می‌دهد.

ارائه‌دهندگان موجود در فید از دستورالعمل‌های هشدارهای عمومی Google پیروی می‌کنند. Google ممکن است فهرست ارائه‌دهندگان را در هرزمانی به‌روز کند.

کشور نمایندگی زبان‌های پشتیبانی‌شده
استرالیا ACT Emergency Services Agency (ACT ESA) en-US
New South Wales Rural Fire Service (NSW RFS) en-AU
South Australian Country Fire Service (SA CFS) en-AU
Tasmania Fire Service (TFS) en-US
Queensland Fire and Emergency Services (QFES) en-AU
اتریش ‫GeoSphere Austria ازطریق MeteoAlarm de-DE، en-GB
بلژیک ‫Royal Meteorological Institute of Belgium ازطریق MeteoAlarm en-GB، fr-BE، nl-BE
بوسنی و هرزگوین ‫Federal Hydro-meteorological Institute (FHMZ) ازطریق MeteoAlarm bs
بلغارستان ‫National Institute of Meteorology & Hydrology ازطریق MeteoAlarm bg، en-GB
برزیل Centro Nacional de Gerenciamento de Riscos e Desastres (CENAD) pt-BR
Instituto Nacional de Meteorologia (INMET) pt-BR
کلمبیا Unidad Nacional para la Gestión del Riesgo de Desastres (UNGRD) es
ساحل عاج Société d'Exploitation et de Développement Aéroportuaire, Aéronautique et Météorologique fr
کرواسی ‫Croatian Meteorological and Hydrological Service ازطریق MeteoAlarm hr-HR، en-GB
قبرس ‫Department of Meteorology ازطریق MeteoAlarm el-GR، en-GB
جمهوری چک ‫Czech Hydrometeorological Institute ازطریق MeteoAlarm en-GB، cs
دانمارک ‫Danish Meteorological Institute ازطریق MeteoAlarm en-GB، da-DK
اکوادور Instituto Nacional de Meteorología e Hidrología es
استونی ‫Ministry of Climate ازطریق MeteoAlarm et-EE
فنلاند ‫Finnish Meteorological Institute ازطریق MeteoAlarm fi-FI، sv-SE، en-GB
فرانسه ‫Météo-France ازطریق MeteoAlarm en-GB، fr-FR
آلمان DWD - The German Weather Service de-DE
غنا Agence Nationale de la Météorologie fr
یونان ‫Hellenic National Meteorological Service ازطریق MeteoAlarm en-GB، el-GR
مجارستان ‫HungaroMet Nonprofit Zrt ازطریق MeteoAlarm en-GB، hu-HU
ایسلند ‫Icelandic Meteorological Office ازطریق MeteoAlarm en-GB، is-IS
ایرلند ‫Met Eirann ازطریق MeteoAlarm en-GB
ایتالیا ‫Italian Meteorological Service ازطریق MeteoAlarm it-IT، en-GB
جامائیکا Meteorological Service of Jamaica en-JM
ژاپن Japan Meteorological Agency (JMA) ja
لتونی ‫Latvian Environment, Geology and Meteorology Centre ازطریق MeteoAlarm en-GB، lv
لیتوانی ‫Lithuanian Hydrometeorological Service ازطریق MeteoAlarm en-GB، lt-LT
لوکزامبورگ ‫MeteoLux ازطریق MeteoAlarm fr-FR، de-DE، en-GB
ماداگاسکار Météo Madagascar en، fr
مکزیک Centro de Instrumentación y Registro Sísmico A.C. (CIRES) es-MX
هلند ‫Royal Netherlands Meteorological Institute ازطریق MeteoAlarm nl-NL، en-GB
مقدونیه شمالی ‫National Hydrometeorological Service ازطریق MeteoAlarm en-GB
نروژ ‫Norwegian Meteorological Institute ازطریق MeteoAlarm en-GB، no
نیوزیلند GNS Science (GeoNet) en-NZ
MetService en-US
فیلیپین Philippine Atmospheric, Geophysical & Astronomical Services Administration (PAGASA) en-US
لهستان ‫Institute of Meteorology and Water Management ازطریق MeteoAlarm pl-PL، en-GB
پرتغال ‫Portuguese Institute for Sea and Atmosphere ازطریق MeteoAlarm en-GB، pt-PT
رومانی ‫سازمان ملی هواشناسی ازطریق MeteoAlarm en-GB، ro-RO
صربستان ‫مؤسسه هیدرومتئورولوژی جمهوری صربستان ازطریق MeteoAlarm en-GB، sr
سنگاپور Meteorological Service Singapore en-US
اسلواکی ‫Slovak Hydrometeorological Institute ازطریق MeteoAlarm sk، en-GB
اسلوونی ‫Hydrometeorological Institute of Slovenia ازطریق MeteoAlarm en-GB، sl
جزایر سلیمان Solomon Islands Meteorological Services en
کرهٔ جنوبی Korea Meteorological Administration en-US، ko-KR
اسپانیا ‫State Meteorological Agency ازطریق MeteoAlarm en-GB، es-ES
سوئد ‫Swedish Meteorological and Hydrological Institute ازطریق MeteoAlarm en-GB، sv-SE
سوئیس ‫Federal Office of Meteorology and Climatology MeteoSwiss ازطریق MeteoAlarm en،‏ de،‏ fr،‏ it
تایوان National Science and Technology Center for Disaster Reduction (NCDR) zh-TW
تایلند Thai Meteorological Department th-TH
بریتانیا ‫Met Office ازطریق MeteoAlarm en-GB
کارگزاری محیط‌زیست پادشاهی متحد
ایالات متحده National Tsunami Warning Center en-US
US National Weather Service en-US
ویتنام مرکز ملی پیش‌بینی هیدرومتئورولوژی (هواشناسی و آب‌شناسی) en-VN، vi-VN

اِسناد

در همه نمایشگرهایی که داده‌ها ارائه می‌شود، برنامه مشتری باید بااستفاده از فیلد dataSource، ارجاعی به منبع اصلی داشته باشد:

"dataSource": {
        "publisher": "NOAA",
        "name": "National Weather Service",
        "authorityUri": "https://www.weather.gov/"
      }

ذکر منبع باید شامل نام کامل منبع داده (همان‌طور که در فیلد name ارائه شده است) و اَبَرپیوند به منبع داده بااستفاده از نشانی وب ارائه‌شده در فیلد authorityUri باشد (برای مثال، «سرویس ملی هواشناسی»).

انواع رویدادهای آب‌وهوایی

انواع رویدادهای آب‌وهوایی زیر پشتیبانی می‌شوند:

انواع رویدادهای آب‌وهوایی
ACID_RAIN
AVALANCHE
BLIZZARD
BLOWING_SNOW
COASTAL_FLOOD
COASTAL_HAZARD
COLD
CYCLONE
DROUGHT
EXTRATROPICAL_CYCLONE
FIRE_WEATHER
FLASH_FLOOD
FLOOD
FOG
FREEZING
FREEZING_AIR_TEMPERATURE
FREEZING_DRIZZLE
FREEZING_RAIN
FROST
GALE
GLAZE
HAIL
HAZARDOUS_SEAS
HEAT
HUMIDITY
HURRICANE
ICE_STORM
LAKE_EFFECT_SNOW
MONSOON
MUDDY_FLOOD
OUTFLOW
RAIN
RIVER_FLOODING
SEVERE_THUNDERSTORM_WARNING
SNOW
SNOWSQUALL
STORM
STORM_SURGE
THUNDER
THUNDERSTORM
TORNADO
TORNADO_WARNING
TROPICAL_CYCLONE
TROPICAL_CYCLONE_WARNINGS_AND_WATCHES
TROPICAL_DISTURBANCE
TROPICAL_STORM
TYPHOON
WIND
WIND_CHILL
WIND_WAVE
WINTER_STORM
WILDFIRE
BUSHFIRE
FIRE
LANDSLIDE
EARTHQUAKE
DUST_STORM
AFTERSHOCK
TSUNAMI
VOLCANIC_ASH
VOLCANIC_ERUPTION
RADIATION

رفتار ترجمه پاسخ

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"
}

امتحان کنید!

با «کاوشگر میاناهای برنامه‌سازی کاربردی» می‌توانید درخواست‌های نمونه ایجاد کنید تا با میانای برنامه‌سازی کاربردی و گزینه‌های آن آشنا شوید.

  1. نماد API api را در سمت راست صفحه انتخاب کنید.

  2. درصورت تمایل، پارامترهای درخواست را ویرایش کنید.

  3. دکمه اجرا را انتخاب کنید. در کادر گفتگو، حسابی را که می‌خواهید برای درخواست استفاده شود انتخاب کنید.

  4. در پانل «کاوشگر API»، نماد تمام‌صفحه تمام‌صفحه را انتخاب کنید تا پنجره «کاوشگر API» ازهم باز شود.