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

نقطه پایانی publicAlerts جزئیات هشدارهای رویدادهای آب‌وهوایی خاص را که توسط سازمان‌های معتبر ملی و بین‌المللی صادر شده‌اند ارائه می‌دهد. این هشدارها اطلاعات حیاتی و احتمالاً نجات‌دهنده ارائه می‌دهند.

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

• بارش: باران، برف، تگرگ، خشکسالی، و غیره
• دمای شدید: سرما، گرما، یخبندان، سرمازدگی، سوز باد، و رطوبت
• رویدادهای باد و توفان: کولاک، توفند، گردباد، توفان حاره‌ای، توفان تندری، و غیره
• اختلالات دید: مه، طوفان گردوغبار، و کولاک برف
• خطرات مرتبط با آب: سیل، سونامی، خیزاب، خطرات ساحلی، و غیره
• رویدادهای ژئوفیزیکی و زمین‌شناسی: زمین‌لرزه، رانش زمین، و فعالیت‌های آتشفشانی
• حوادث آتش‌سوزی: آتش‌سوزی جنگل، آب‌وهوای مستعد آتش‌سوزی، و غیره

برای فهرست کامل رویدادهای آب‌وهوایی پشتیبانی‌شده، انواع رویدادهای آب‌وهوایی را ببینید.

هشدارها ممکن است حاوی شرح‌های بومی‌سازی‌شده باشند یا نباشند، که این امر به آنچه از منبع داده دردسترس است بستگی دارد. به‌دلیل محدودیت‌های منبع داده، اطلاعات به‌همان صورتی که هست (محتوای خام) ارائه می‌شود. برای اطلاعات بیشتر درباره منابع هشدار آب‌وهوا، منابع داده را ببینید.

‫API اطلاعات زیر را برای هشدار آب‌وهوایی مشخصی برمی‌گرداند:

• نوع رویداد آب‌وهوایی مرتبط با هشدار
• فهرستی از مناطق تحت‌تأثیر قرارگرفته به‌همراه مختصاتی که مرزهای جغرافیایی آن مناطق را تعریف می‌کند
• خلاصه یک‌جمله‌ای از رویداد آب‌وهوایی
• سطوح شدت، قطعیت، و فوریت
• شرح دستورالعمل‌های اقدام-توصیه برای مخاطب هدف
• توصیه‌های ایمنی
• زمان شروع و پایان هشدار
• نام و وب‌سایت مرجع انتشار

APIs Explorer به شما امکان می‌دهد درخواست‌های زنده ایجاد کنید تا بتوانید با API و گزینه‌های API آشنا شوید:

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

برای درخواست اطلاعات هشدار آب‌وهوا، درخواست HTTP GET را به این نشانی ارسال کنید:

https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE&languageCode=LANGUAGE_CODE

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

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

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

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

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

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

اِسناد

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

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

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

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

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

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

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 Explorer می‌توانید درخواست‌های نمونه ایجاد کنید تا با API و گزینه‌های API آشنا شوید.

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

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

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

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