חיפוש מזג האוויר

הכלי lookup_weather מאפשר למודל שפה גדול (LLM) לאחזר את תנאי הסביבה במיקום מסוים: מזג האוויר, איכות האוויר ורמת האבקנים. בבקשה אחת אפשר לשלוח שאילתה לגבי אחת, שתיים או כל שלוש היכולות הסביבתיות של מזהה מקום, כתובת או קואורדינטות של קו רוחב/קו אורך.

בקשות ששולחות שאילתות רק לגבי מזג האוויר או איכות האוויר הנוכחית והחזויה מחויבות לפי המק"ט Maps Grounding Essentials. 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 נבדקים באזור הזמן המקומי של המיקום המבוקש. בטבלה הבאה מפורטים טווחי תאריכים והמק"טים שנתמכים בכל יכולת:

פונקציה התנאים הנוכחיים (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 נמצא מחוץ לטווח הנתמך של כל יכולת שביקשתם.

אפשרויות לבקשות

מודל ה-LLM מגדיר את האפשרויות האלה כשהוא קורא לכלי, על סמך הבקשה של המשתמש ותיאור הכלי. אתם יכולים להשפיע על האפשרויות שהמודל משתמש בהן באמצעות ההוראות שלכם. מידע נוסף זמין במאמר שליטה בשימוש ב-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.

אפשרויות מתקדמות

שתי אפשרויות לבחירת המק"ט של Maps Grounding Pro. בקשה מחויבת במסגרת המק"ט Pro כשאחת מהאפשרויות מוחזרת בתגובה. למידע על כללי החיוב של יכולות מרובות, ראו חיוב ומכסות. בטבלה הבאה מתוארות האפשרויות של Pro:

אפשרות Pro מתי כדאי להשתמש בו
POLLEN ב-capabilities המשתמש שואל על רמות האבקנים, אלרגיות עונתיות, אבקנים של עצים, דשא או עשבים, או מינים ספציפיים של צמחים אלרגניים.
AIR_QUALITY בcapabilities עם date לפני היום או hour בעבר המשתמש שואל על היסטוריית איכות האוויר, העשן או הזיהום ב-30 הימים האחרונים באזור הזמן של המיקום.

כל שאר הבקשות ל-lookup_weather מחויבות במסגרת המק"ט של Essentials, כולל:

  • כל הבקשות של WEATHER (היסטוריה נוכחית של 24 שעות, ותחזיות שעתיות או יומיות ל-10 ימים).
  • בקשות לנתונים נוכחיים, לנתונים של יום שלם (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
}

בדוגמה הבאה נשלחת אותה בקשה ל-method‏ 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 יומיים. השעות של הזריחה, השקיעה, זריחת הירח ושקיעת הירח הן חותמות זמן ב-UTC.
    • ‫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 מבקש שניים או שלושה דומיינים סביבתיים באותה קריאה:

  • בקשה מחויבת לפי רמת המק"ט הגבוהה ביותר מבין היכולות שבוצעו בהצלחה ומוחזרות בתגובה:
    • אם התשובה כוללת pollen או airQuality היסטורי (date לפני היום או hour בעבר באזור הזמן של המיקום), הבקשה מחויבת לפי המק"ט של Maps Grounding Pro. בקשה של POLLEN וגם של AIR_QUALITY היסטורי בקריאה אחת עדיין נחשבת לאירוע אחד שניתן לחיוב ב-Pro.
    • אחרת, הבקשה מחויבת לפי מק"ט Maps Grounding Essentials.
  • אם בקשה כוללת כמה יכולות, ואחת מהן היא יכולת Pro שלא נכללת בתגובה (כי היא לא זמינה במיקום, לא נתמכת בטווח תאריכים או נכשלה באופן זמני), ורק יכולות Essentials נכללות בתגובה, החיוב על הבקשה יהיה לפי המק"ט של Essentials.

המכסה של lookup_weather היא 300 שאילתות לדקה לכל פרויקט, והיא משותפת לשני המק"טים. למידע על מחירים, ראו את טבלת התמחור הראשית ואת טבלת התמחור בהודו.