البحث عن حالة الطقس

تتيح أداة lookup_weather لنموذج لغوي كبير استرداد الظروف البيئية لموقع جغرافي معيّن، مثل الطقس وجودة الهواء وحبوب اللقاح. يمكن لطلب واحد الاستعلام عن إحدى الإمكانات البيئية الثلاث أو اثنتين منها أو جميعها لرقم تعريف مكان أو عنوان أو إحداثيات خطوط العرض/الطول.

تتم فوترة الطلبات التي تستعلم فقط عن الطقس أو جودة الهواء الحالية والمتوقّعة ضمن رمز التخزين التعريفي لأساسيات الربط بخرائط Google. يضيف الإصدار Pro توقعات يومية حول حبوب اللقاح وبيانات سابقة حول جودة الهواء لمدة تصل إلى 30 يومًا.

يمكنك استدعاء lookup_weather من خلال خادم MCP أو كطريقة REST لـ lookupWeather. توضّح هذه الصفحة الإمكانات البيئية وخيارات الطلبات وخيارات Pro وبنية الاستجابة وقواعد الفوترة. للاطّلاع على المخططات الكاملة، يُرجى مراجعة مرجع lookup_weather MCP ومرجع lookupWeather REST.

الإمكانات والأُطر الزمنية

استخدِم مصفوفة capabilities لاختيار النطاقات البيئية التي تريد عرضها (WEATHER أو AIR_QUALITY أو POLLEN). يجب استخدام capabilities عند ضبط weather_options أو air_quality_options أو language_code. في حال حذف capabilities وweather_options وair_quality_options وlanguage_code، يتم تشغيل lookup_weather في وضع الطقس القديم ويعرض حقول الطقس المسطّحة ذات المستوى الأعلى.

يتم تقييم جميع قيم date وhour في المنطقة الزمنية المحلية للموقع الجغرافي المطلوب. يلخّص الجدول التالي النطاقات الزمنية المتوافقة ورقم SKU لكل ميزة:

إمكانية الأحوال الجوية الحالية (تم حذف date وhour) الأحوال الجوية السابقة توقُّع الأحوال الجوية رمز التخزين التعريفي
WEATHER الطقس الحالي ما يصل إلى 24 ساعة في الماضي (يتطلب كلاً من date وhour، ولا يمكن استخدام date في الماضي بدون hour) توقّعات الطقس كل ساعة لمدة تصل إلى 240 ساعة (10 أيام) عند ضبط hour، أو توقّعات الطقس اليومية لمدة تصل إلى 10 أيام عند ضبط date فقط Essentials
AIR_QUALITY جودة الهواء الحالية لكل ساعة ما يصل إلى 720 ساعة (30 يومًا) في الماضي لساعة واحدة عند ضبط date وhour، أو ما يصل إلى 29 يومًا قبل اليوم (ما يصل إلى 24 إدخالاً في الساعة) عند ضبط date فقط ما يصل إلى 96 ساعة (4 أيام) في المستقبل لساعة واحدة عند ضبط date وhour، أو من اليوم إلى 3 أيام بعد اليوم (ما يصل إلى 24 إدخالاً في الساعة) عند ضبط date فقط أساسيات الطقس الحالي واليوم بالكامل والتوقعات ‫Pro لـ date قبل اليوم أو hour سابق عند إرجاعه في الردّ
POLLEN توقعات انتشار حبوب اللقاح اليومية لليوم الحالي غير متاح (يؤدي إلى ظهور خطأ INVALID_ARGUMENT) توقعات حبوب اللقاح اليومية لمدة تصل إلى 4 أيام بعد اليوم، ولمدة 5 أيام بما في ذلك اليوم (يتم تجاهل hour بالنسبة إلى حبوب اللقاح) Pro عند عرضها في الردّ

بالنسبة إلى AIR_QUALITY، يتم تثبيت نافذة التوقعات التي تمتد من 720 ساعة في الماضي إلى 96 ساعة في المستقبل على الساعة الحالية. تغطي طلبات اليوم الكامل (date بدون hour) الفترة من 00:00 إلى 23:00 بالتوقيت المحلي ويجب أن تندرج ضمن هذه الفترة، أي من 29 يومًا قبل اليوم وحتى ثلاثة أيام بعد اليوم.

عندما يتضمّن الطلب إمكانات متعددة، يتم تقييم النطاق الزمني لكل إمكانية بشكل مستقل. إذا كان date وhour المطلوبان ضمن النطاق لإمكانية واحدة على الأقل مطلوبة، ستعرض الاستجابة حاويات الإمكانات المتوافقة وستحذف أي إمكانية لا يتوافق نطاقها الزمني. على سبيل المثال، يؤدي طلب AIR_QUALITY وPOLLEN لتاريخ سابق خلال 30 يومًا إلى عرض airQuality وحذف pollen. يعرض الطلب الخطأ INVALID_ARGUMENT إذا كانت قيمة date أو hour خارج النطاق المسموح به لكل ميزة مطلوبة.

خيارات الطلب

يضبط النموذج اللغوي الكبير هذه الخيارات عند استدعاء الأداة، استنادًا إلى طلب المستخدم ووصف الأداة. يمكنك التأثير في الخيارات التي يستخدمها النموذج من خلال تعليماتك الخاصة، راجِع التحكّم في استخدام Pro.

يوضّح الجدول التالي خيارات الطلبات في lookup_weather:

Option الوصف
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. تتم فوترة الطلب ضمن رمز التخزين التعريفي Pro عند عرض أيّ من الخيارَين في الردّ. للاطّلاع على قواعد الفوترة المتعلّقة بالميزات المتعدّدة، يُرجى مراجعة الفوترة والحصص. يوضّح الجدول التالي خيارات Pro:

خيار Pro حالات الاستخدام
POLLEN في capabilities يسأل المستخدم عن مستويات حبوب اللقاح أو الحساسية الموسمية أو حبوب اللقاح من الأشجار أو الأعشاب أو الحشائش أو أنواع نباتية معيّنة مسبّبة للحساسية.
‫AIR_QUALITY في capabilities مع date قبل اليوم أو hour سابق يسأل المستخدم عن جودة الهواء أو الدخان أو التلوث في الماضي خلال آخر 30 يومًا في المنطقة الزمنية للموقع الجغرافي.

تتم فوترة جميع طلبات lookup_weather الأخرى ضمن رمز التخزين التعريفي Essentials، بما في ذلك:

  • جميع طلبات WEATHER (الحالية، وسجلّ الـ 24 ساعة، والتوقعات لكل ساعة أو يوميًا لمدة 10 أيام)
  • طلبات AIR_QUALITY الحالية لليوم الكامل (تم ضبط date على اليوم بدون hour) والتوقعات، بما في ذلك الطلبات التي تضبط 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
}

يرسل المثال التالي الطلب نفسه إلى طريقة REST‏ lookupWeather:

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 بمفتاح واجهة برمجة التطبيقات.

الردّ

عندما يحدّد الطلب 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[]: يحتوي على إدخال واحد لطلبات البحث الحالية أو التي تم إجراؤها خلال ساعة واحدة، أو ما يصل إلى 24 إدخالاً تغطي اليوم المحلي بالكامل (من 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 نطاقَين أو ثلاثة نطاقات بيئية في الطلب نفسه:

  • تتم فوترة الطلب ضمن أعلى مستوى لوحدة تخزين سلع معيّنة من بين الميزات التي تنجح ويتم عرضها في الردّ:
  • إذا تم حذف إحدى ميزات Pro في طلب متعدد الميزات، لأنّها غير متاحة للموقع الجغرافي أو خارج النطاق الزمني المتوافق أو تعذّر تنفيذها مؤقتًا، وتم عرض ميزات Essentials فقط في الردّ، يتم تحصيل رسوم الطلب ضمن رمز التخزين التعريفي لـ Essentials.

تبلغ حصة lookup_weather ‏300 طلب بحث في الدقيقة لكل مشروع، وتتم مشاركتها من خلال كل من رمزَي التخزين التعريفيَين. للاطّلاع على الأسعار، يُرجى مراجعة جدول الأسعار الرئيسي وجدول الأسعار في الهند.