جستجوی آب‌وهوا

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

درخواست‌هایی که فقط آب‌وهوا یا کیفیت هوای فعلی و پیش‌بینی‌شده را پرسمان می‌کنند، تحت واحد نگهداری موجودی ضروریات زمینه‌سازی Maps صورت‌حساب می‌شوند. Pro پیش‌بینی گرده روزانه و کیفیت هوای گذشته تا ۳۰ روز قبل را اضافه می‌کند.

می‌توانید lookup_weather را ازطریق سرور MCP یا به‌عنوان روش REST lookupWeather فراخوانی کنید. این صفحه قابلیت‌های محیطی، گزینه‌های درخواست، گزینه‌های Pro، ساختار پاسخ، و قوانین صورت‌حساب را شرح می‌دهد. برای مشاهده طرح‌واره‌های کامل، به lookup_weather مرجع MCP و lookupWeather مرجع REST مراجعه کنید.

قابلیت‌ها و افق‌های زمانی

از آرایه capabilities برای انتخاب دامنه‌های محیطی که باید برگردانده شوند استفاده کنید (WEATHER، AIR_QUALITY، POLLEN). هرگاه weather_options، air_quality_options، یا language_code را تنظیم کنید، capabilities الزامی است. اگر capabilities، weather_options، air_quality_options، و language_code را حذف کنید، lookup_weather در حالت آب‌وهوای قدیمی اجرا می‌شود و فیلدهای آب‌وهوای سطح بالا را به‌صورت مسطح برمی‌گرداند.

همه مقادیر date و hour در منطقه زمانی محلی مکان درخواست‌شده ارزیابی می‌شوند. جدول زیر محدوده‌های زمانی پشتیبانی‌شده و SKU را برای هر قابلیت خلاصه می‌کند:

قابلیت وضعیت فعلی (date و hour حذف شده است) شرایط گذشته شرایط پیش‌بینی‌شده واحد نگهداری موجودی
WEATHER آب و هوای فعلی تا ۲۴ ساعت گذشته (به هر دو date و hour نیاز دارد؛ date گذشته بدون hour پشتیبانی نمی‌شود) پیش‌بینی ساعتی تا ۲۴۰ ساعت (۱۰ روز) وقتی hour تنظیم شده باشد، یا پیش‌بینی روزانه تا ۱۰ روز وقتی فقط date تنظیم شده باشد ‏Essentials
AIR_QUALITY کیفیت هوای ساعتی کنونی تا ۷۲۰ ساعت (۳۰ روز) در گذشته برای یک ساعت وقتی date و hour تنظیم شده باشد، یا تا ۲۹ روز قبل‌از امروز (تا ۲۴ ورودی ساعتی) وقتی فقط date تنظیم شده باشد تا ۹۶ ساعت (۴ روز) در آینده برای یک ساعت وقتی date و hour تنظیم شده باشد، یا امروز تا ۳ روز بعداز امروز (تا ۲۴ ورودی ساعتی) وقتی فقط date تنظیم شده باشد ضروریات برای وضعیت کنونی، کل روز امروز، و پیش‌بینی. Pro برای date قبل‌از امروز یا hour گذشته وقتی در پاسخ برگردانده شود
POLLEN پیش‌بینی روزانه گرده گل برای روز جاری پشتیبانی نمی‌شود (خطای INVALID_ARGUMENT برمی‌گرداند) پیش‌بینی روزانه گرده تا ۴ روز بعداز امروز، برای ۵ روز ازجمله امروز (hour برای گرده نادیده گرفته می‌شود) Pro وقتی در پاسخ برگردانده می‌شود

برای AIR_QUALITY، پنجره پیش‌بینی ۷۲۰ ساعت گذشته تا ۹۶ ساعت آینده به ساعت فعلی متصل است. درخواست‌های تمام‌روز (date بدون hour) 00:00 تا 23:00 وقت محلی را پوشش می‌دهند و باید در آن پنجره قرار بگیرند—در عمل از ۲۹ روز قبل‌از امروز تا سه روز بعداز امروز.

وقتی درخواستی شامل چندین قابلیت باشد، افق زمانی هر قابلیت به‌طور مستقل ارزیابی می‌شود. اگر date و hour درخواست‌شده در محدوده حداقل یک توانایی درخواست‌شده باشد، پاسخ، محفظه‌های توانایی پشتیبانی‌شده را برمی‌گرداند و هر توانایی‌ای را که محدوده زمانی آن پشتیبانی نمی‌شود حذف می‌کند. برای مثال، درخواست AIR_QUALITY و POLLEN برای تاریخ گذشته‌ای در ۳۰ روز گذشته airQuality را برمی‌گرداند و pollen را حذف می‌کند. اگر date یا hour خارج از محدوده پشتیبانی‌شده هر قابلیت درخواست‌شده باشد، درخواست با INVALID_ARGUMENT خطا مواجه می‌شود.

گزینه‌های درخواست

«مدل زبانی بزرگ» این گزینه‌ها را هنگام فراخوانی ابزار، براساس درخواست کاربر و شرح ابزار تنظیم می‌کند. می‌توانید با دستورالعمل‌های خودتان بر گزینه‌هایی که مدل استفاده می‌کند تأثیر بگذارید؛ کنترل استفاده از Pro را ببینید.

جدول زیر گزینه‌های درخواست برای lookup_weather را شرح می‌دهد:

گزینه شرح
location الزامی. مکان موردنظر برای پُرسمان که به‌صورت address (نشانی، شهر، یا نام نشانگر مکانی قابل‌خواندن برای انسان)، place_id، یا lat_lng (latitude و longitude) مشخص شده است.
capabilities اختیاری. یک یا چند مقدار از WEATHER،‏ AIR_QUALITY، و POLLEN. مقادیر تکراری حذف می‌شوند. هنگام تنظیم weather_options، air_quality_options، یا language_code الزامی است. وقتی capabilities و همه آن گزینه‌ها حذف شوند، پاسخ آب‌وهوای مسطح قدیمی برگردانده می‌شود.
date اختیاری. تاریخ مدنی محلی (year، month، day) در مکان درخواست‌شده. date و hour را برای شرایط کنونی حذف کنید.
hour اختیاری. ساعت محلی (0 تا 23) در مکان درخواست‌شده. لازم است date تنظیم شود. تنظیم hour بدون date خطای INVALID_ARGUMENT را برمی‌گرداند.
language_code اختیاری. کد زبان BCP-47 برای نوشتار بومی‌سازی‌شده در پاسخ، مثل en، ja، یا fr-CA. پیش‌فرض‌ها به en.
weather_options.units_system اختیاری. سیستم واحد برای مقادیر آب‌وهوا: METRIC (پیش‌فرض؛ سلسیوس، کیلومتر در ساعت، میلی‌متر) یا IMPERIAL (فارنهایت، مایل در ساعت، اینچ). اگر WEATHER درخواست نشده باشد، نادیده گرفته می‌شود.
air_quality_options.include_pollutant_concentration اختیاری. وقتی true، airQuality.hourlyResults[].pollutants[] شامل غلظت آلاینده‌های اندازه‌گیری‌شده، منابع انتشار کربن، و تأثیرات بر سلامتی است. پیش‌فرض‌ها به false. اگر AIR_QUALITY درخواست نشده باشد، نادیده گرفته می‌شود.
air_quality_options.index_region_code اختیاری. کد کشور یا منطقه دوحرفی ISO 3166-1 alpha-2 (برای مثال، US، FR، یا CN) که برای انتخاب مقیاس «شاخص کیفیت هوا» (AQI) محلی درکنار «شاخص کیفیت هوای جهانی» (UAQI) استفاده می‌شود. به‌طور پیش‌فرض روی منطقه مکان درخواست‌شده تنظیم می‌شود. اگر AIR_QUALITY درخواست نشده باشد، نادیده گرفته می‌شود.

گزینه‌های Pro

دو گزینه Maps Grounding Pro SKU را انتخاب می‌کنند. وقتی هرکدام از این گزینه‌ها در پاسخ برگردانده شود، درخواست تحت شناسه Pro SKU صورت‌حساب می‌شود. برای قوانین صدور صورت‌حساب چندقابلیتی، صدور صورت‌حساب و سهمیه‌ها را ببینید. جدول زیر گزینه‌های Pro را شرح می‌دهد:

گزینه Pro زمان استفاده از آن
‫POLLEN در capabilities کاربر درباره سطح گرده، آلرژی‌های فصلی، گرده درخت، چمن، یا علف، یا گونه‌های گیاهی آلرژی‌زای خاص سؤال می‌پرسد.
‫AIR_QUALITY در capabilities با date قبل‌از امروز یا hour گذشته کاربر درباره سابقه کیفیت هوا، دود، یا آلودگی در ۳۰ روز گذشته در منطقه زمانی مکان موردنظر سؤال می‌کند.

همه درخواست‌های lookup_weather دیگر تحت SKU «ضروریات» صورت‌حساب می‌شوند، ازجمله:

  • همه درخواست‌های WEATHER (پیش‌بینی‌های فعلی، سابقه ۲۴ ساعته، و پیش‌بینی‌های ساعتی یا روزانه ۱۰ روزه).
  • کنونی، کل روز امروز (date روی امروز بدون hour تنظیم شده است)، و پیش‌بینی AIR_QUALITY درخواست، ازجمله درخواست‌هایی که include_pollutant_concentration را روی true تنظیم می‌کنند یا index_region_code را مشخص می‌کنند.

مثال

درخواست MCP زیر آب‌وهوای فعلی، کیفیت هوا (با غلظت آلاینده‌ها)، و پیش‌بینی گرده‌های امروز در توکیو را درخواست می‌کند. چون capabilities شامل POLLEN است، درخواست تحت شناسه Pro صورت‌حساب می‌شود:

{
  "method": "tools/call",
  "params": {
    "name": "lookup_weather",
    "arguments": {
      "location": {"address": "Tokyo, Japan"},
      "capabilities": ["WEATHER", "AIR_QUALITY", "POLLEN"],
      "weather_options": {
        "units_system": "METRIC"
      },
      "air_quality_options": {
        "include_pollutant_concentration": true
      },
      "language_code": "en"
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

مثال زیر همان درخواست را به روش lookupWeather REST ارسال می‌کند:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "location": {"address": "Tokyo, Japan"},
  "capabilities": ["WEATHER", "AIR_QUALITY", "POLLEN"],
  "weatherOptions": {"unitsSystem": "METRIC"},
  "airQualityOptions": {"includePollutantConcentration": true},
  "languageCode": "en"
}' \
"https://mapstools.googleapis.com/v1:lookupWeather"

API_KEY را با کلید میانای API خودتان جایگزین کنید.

پاسخ

وقتی درخواستی capabilities را مشخص می‌کند، پاسخ، محفظه‌های مختص دامنه را برای هر قابلیت درخواست‌شده در کنار فراداده مکان پر می‌کند:

  • returnedLocation: مکان حل‌شده (address، placeId، یا latLng، مطابق با نوع ورودی location) برای داده‌های محیطی.
  • ‫timeZone: شناسه منطقه زمانی IANA حل‌شده برای مکان، مثل "America/Los_Angeles" یا "Asia/Tokyo".
  • weather: وقتی WEATHER درخواست شود، تکمیل می‌شود:
    • dateTime (برای پُرسمان‌های فعلی و ساعتی)، به‌عنوان مُهر زمان UTC، یا date (برای پُرسمان‌های پیش‌بینی روزانه). برای نمایش زمان‌های محلی، dateTime را با فیلد timeZone تبدیل کنید.
    • دما (temperature، feelsLikeTemperature، heatIndex، یا روزانه maxTemperature، minTemperature، feelsLikeMaxTemperature، feelsLikeMinTemperature، maxHeatIndex).
    • ‫weatherCondition، precipitation، wind، airPressure، relativeHumidity، uvIndex، thunderstormProbability، cloudCover، و sunEvents و moonEvents روزانه. زمان طلوع آفتاب، غروب آفتاب، طلوع ماه، و غروب ماه مُهرهای زمان ساعت هماهنگ جهانی هستند.
    • attribution: ارجاعی که باید با داده‌های آب‌وهوا نشان دهید.
  • airQuality: وقتی AIR_QUALITY درخواست شود، تکمیل می‌شود:
    • hourlyResults[]: حاوی یک ورودی برای پُرسمان‌های فعلی یا تک‌ساعته است، یا حداکثر ۲۴ ورودی که کل روز محلی را پوشش می‌دهد (00:00 تا 23:00) وقتی فقط date تنظیم شده باشد. وقتی date امروز باشد و hour حذف شده باشد، ورودی‌ها ساعت‌های تاریخی قبلی امروز، ساعت فعلی، و ساعت‌های پیش‌بینی‌شده باقی‌مانده را ترکیب می‌کنند. هر ورودی شامل موارد زیر است:
      • dateTime: تاریخ و زمان مدنی محلی (year، month، day، hours، minutes، seconds، و utcOffset) در منطقه زمانی مکان.
      • indexes[]: شاخص کیفیت هوای جهانی و، درصورت دردسترس بودن، شاخص کیفیت هوای محلی (displayName، value، valueDisplay، category، و dominantPollutant).
      • pollutants[]: وقتی include_pollutant_concentration true باشد، تکمیل می‌شود (displayName، fullName، concentration در ppb یا µg/m³، و additionalInfo با انتشار sources و سلامت effects).
      • ‫healthRecommendations: راهنمایی برای generalPopulation، elderly، lungDiseasePopulation، heartDiseasePopulation، athletes، pregnantWomen، و children.
    • ‫attribution: ارجاعی که باید با داده‌های کیفیت هوا نشان دهید.
  • pollen: وقتی POLLEN درخواست شود، تکمیل می‌شود:
    • dailyForecast: پیش‌بینی گرده برای date درخواست‌شده:
      • date: تاریخ تقویم مدنی پیش‌بینی.
      • categories[]: دسته‌های کلی آلرژن (Tree، Grass، و Weed)، هرکدام با displayName، inSeason، «شاخص جهانی گرده» index (مقیاس 0 تا 5، category، و description)، و healthRecommendations[].
      • plantSpecies[]: گونه‌های گیاهی آلرژی‌زای خاص (مانند توس، آمبروسیا، یا سدر ژاپنی)، هرکدام با code،‏ displayName، family گیاه‌شناسی، inSeason، «شاخص گرده جهانی» index، season شکوفایی معمول، و crossReactions.
    • attribution: ارجاعی که باید همراه با داده‌های گرده نشان دهید.

دردسترس بودن جزئی در قابلیت‌ها

وقتی درخواستی شامل چندین قابلیت باشد، هر قابلیت به‌طور مستقل ارزیابی و واکشی می‌شود. اگر یکی از قابلیت‌ها برای مکان درخواست‌شده دردسترس نباشد، خارج از محدوده زمانی پشتیبانی‌شده باشد، یا به‌طور موقت ناموفق باشد درحالی‌که حداقل یک قابلیت دیگر موفق باشد، پاسخ کانتینرهای قابلیت دردسترس را برمی‌گرداند و کانتینر ناموفق یا غیرقابل‌دسترس را حذف می‌کند. درخواست فقط درصورتی با خطا مواجه می‌شود که همه قابلیت‌های درخواست‌شده ناموفق باشند.

برای جزئیات کامل فیلد، به مرجع lookup_weather مراجعه کنید.

صورت‌حساب و سهمیه‌ها

هر درخواست lookup_weather یک رویداد قابل‌صورت‌حساب است، حتی زمانی که capabilities دو یا سه دامنه محیطی را در یک تماس درخواست می‌کند:

  • درخواست تحت بالاترین ردیف SKU در میان قابلیت‌هایی که موفق می‌شوند و در پاسخ برگردانده می‌شوند، صورت‌حساب می‌شود:
  • اگر در درخواست چندقابلیتی، قابلیت Pro حذف شود (به‌دلیل دردسترس نبودن برای مکان، خارج بودن از محدوده زمانی پشتیبانی‌شده، یا ناموفق بودن موقت) و فقط قابلیت‌های Essentials در پاسخ برگردانده شود، درخواست تحت شناسه محصول Essentials صورت‌حساب می‌شود.

سهمیه lookup_weather برای هر پروژه ۳۰۰ پُرسمان در دقیقه است که بین هر دو SKU مشترک است. برای قیمت‌گذاری، جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند را ببینید.