חיפוש לאורך המסלול

הכלי search_along_route מאפשר למודל שפה גדול (LLM) למצוא מקומות לאורך מסלול נסיעה באמצעות שאילתה בשפה טבעית, כמו תחנות טעינה לרכב חשמלי בדרך לאגם טאהו או בתי קפה בין סן פרנסיסקו לסן חוזה. הכלי מחזיר סיכום שנוצר על ידי AI של מקומות תואמים וההשלכות של הסטייה מהמסלול. לכל מקום שמוזכר בסיכום, התשובה כוללת גם את מזהה המקום, קואורדינטות של קו רוחב/קו אורך, קישורים למפות Google, שיוך נדרש ומדדי עיקוף.

כל בקשה של search_along_route היא אפשרות Pro ומחויבת במסגרת מק"ט Maps Grounding Pro.

אפשר לקרוא ל-search_along_route דרך שרת ה-MCP או כ-method של searchAlongRoute REST. בדף הזה מתוארות האפשרויות לבקשות, איך לציין מסלול, מה התגובה מכילה ואיך הבקשות מחויבות. הסכימות המלאות מפורטות בחומר העזר בנושא MCP של search_along_route ובחומר העזר בנושא REST של searchAlongRoute.

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

מודל ה-LLM מגדיר את האפשרויות האלה כשהוא קורא לכלי, על סמך הבקשה של המשתמש ותיאור הכלי. אתם יכולים להשפיע על האפשרויות שהמודל משתמש בהן באמצעות ההוראות שלכם. מידע נוסף זמין במאמר שליטה בשימוש ב-Pro.

בטבלה הבאה מתוארות אפשרויות הבקשה של search_along_route:

אפשרות תיאור
text_query חובה. שאילתת החיפוש בשפה טבעית למקומות לאורך המסלול – לדוגמה, ev chargers, coffee או vegetarian restaurants.
retrieval_token, route_endpoints או encoded_polyline חובה. המסלול שלאורכו יתבצע החיפוש. צריך לציין אחד משלושת השדות האלה בכל בקשה. איך מציינים נתיב
travel_mode אופציונלי. אמצעי התחבורה שמשמש לחישוב המסלול ודרכים חלופיות: DRIVE (ברירת מחדל), WALK או BICYCLE. האפשרויות WALK ו-BICYCLE נתמכות רק עם route_endpoints. אין תמיכה ב-TRANSIT. מסלולי WALK נמצאים בגרסת בטא, ולפעמים חסרים בהם מדרכות או שבילים להולכי רגל. חובה להציג את האזהרה הזו למשתמש בכל מסלולי ההליכה שמוצגים באפליקציה.
routing_preference אופציונלי. איך נתוני התנועה משמשים לחישוב זמני המסלול וזמני העיקוף: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (ברירת המחדל) או ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. התכונה ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL משתמשת במצב התנועה בזמן אמת כשהוא זמין, ואין תמיכה בה בWALK או בBICYCLE.
include_extended_details אופציונלי. כשהאפשרות true מופעלת, הסיכום כולל פרטים מורחבים על המקום, כמו תובנות מביקורות, מנות בתפריט, אווירה, טיפים למבקרים, זמינות של מטענים לרכב חשמלי או מחירי דלק. ברירת המחדל היא false.
language_code אופציונלי. קוד השפה בתקן BCP-47 של הסיכום ושל מרחק העיקוף המותאם לשוק המקומי – לדוגמה, en-US או ja. ברירת המחדל היא en-US.
region_code אופציונלי. קוד האזור של המשתמש במאגר CLDR, שמורכב משתי אותיות – לדוגמה, US או CA. משפיע על שמות של מקומות ספציפיים לאזור ויכול להשפיע על התוצאות בהתאם לדין החל.

מציינים מסלול

בכל בקשה ל-search_along_route צריך לציין את המסלול באמצעות אחד משלושה שדות שלא חופפים. אם מגדירים יותר משדה מסלול אחד, או משמיטים את כל שלושת השדות, תוחזר השגיאה INVALID_ARGUMENT.

בטבלה הבאה מוצגת השוואה בין שלוש הדרכים לציין מסלול:

אפשרות מסלול פורמט הקלט אמצעי ההגעה הנתמכים האפליקציה מחזירה את הערך detourDuration מתי כדאי להשתמש בו
retrieval_token המחרוזת retrievalToken מתגובה קודמת של compute_routes (תקפה ל-10 דקות) DRIVE כן הנציג כבר התקשר אל compute_routes כדי לקבל מסלול נסיעה, כולל מסלולים עם עצירות ביניים, והמשתמש מבקש מקומות לאורך המסלול הזה.
route_endpoints אובייקט עם נקודות ציון מסוג origin ו-destination (address,‏ place_id או lat_lng) DRIVE,‏ WALK,‏ BICYCLE כן המשתמש מבקש למצוא מקומות בין שני מיקומים בשלב אחד בלי להפעיל קודם את compute_routes, או שהמסלול הוא ברגל או ברכיבה על אופניים.
encoded_polyline מחרוזת קו פוליגוני מקודד שמייצגת מסלול נסיעה DRIVE לא (מחזיר רק localizedDetourDistance) באפליקציה שלכם כבר יש קו פוליגוני של מסלול ממקור אחר, כמו Routes API.

‫compute_routes ו-search_along_route של הרשת

כשבקשה של compute_routes משתמשת באמצעי התחבורה DRIVE, כל מסלול בתשובה כולל שדה retrievalToken. האסימון הזה תקף ל-10 דקות ומקודד את המסלול המחושב, כולל עצירות ביניים. כשהמשתמש מבקש מקומות לאורך המסלול הזה, ה-LLM יכול להעביר את הערך של retrievalToken בתור retrieval_token ב-search_along_route.

פרטי מקום מורחבים

מגדירים את include_extended_details כ-true כשהבקשה של המשתמש דורשת תובנות איכותיות, תנאים בזמן אמת או מאפיינים מיוחדים לאורך המסלול, כמו:

  • מה כותבי הביקורות אומרים: תובנות שמבוססות על ביקורות, סנטימנט של לקוחות ומשוב.
  • הצעות ספציפיות: פריטים בתפריט, מנות, מאכלים מיוחדים, משקאות או מאפיינים בולטים של העסק.
  • אווירה: עיצוב פנים, אסתטיקה, אווירה או מצב רוח.
  • טיפים שימושיים למבקרים ונתונים בזמן אמת: האם כדאי להזמין מקום מראש, זמני המתנה, כמה המקום עמוס, זמינות של מטענים לרכבים חשמליים, מחירי דלק, חניה ומתקנים.

משאירים את include_extended_details מוגדר ל-false (ברירת המחדל) לחיפושים רגילים לאורך מסלול, כמו חיפוש תחנות דלק, תחנות עצירה או בתי קפה לפי מיקום, שעות פעילות וזמן עיקוף. בקשות עם פרטים מורחבים לוקחות יותר זמן, אבל הן לא מוסיפות חיובים נוספים כי כל בקשה של search_along_route כבר מחויבת במסגרת המק"ט של Pro.

דוגמאות

בקשת ה-MCP הבאה מחפשת תחנות טעינה לרכב חשמלי בין סן פרנסיסקו לאגם טאהו באמצעות route_endpoints ומסלול שמבוסס על מצב התנועה:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "fast EV chargers with a coffee shop nearby",
      "route_endpoints": {
        "origin": {"address": "San Francisco, CA"},
        "destination": {"address": "Lake Tahoe, CA"}
      },
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

בדוגמה הבאה נעשה שימוש ב-retrieval_token מתגובת compute_routes קודמת:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "coffee shops",
      "retrieval_token": "RETRIEVAL_TOKEN"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
}

מחליפים את RETRIEVAL_TOKEN במחרוזת retrievalToken שהוחזרה על ידי compute_routes.

בדוגמה הבאה נשלחת הבקשה הראשונה ל-method‏ searchAlongRoute ב-REST:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "fast EV chargers with a coffee shop nearby",
  "routeEndpoints": {
    "origin": {"address": "San Francisco, CA"},
    "destination": {"address": "Lake Tahoe, CA"}
  },
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchAlongRoute"

מחליפים את הערך API_KEY במפתח ה-API שלכם.

תשובה

התגובה מכילה את השדות הבאים:

  • ‫summary: סיכום בשפה טבעית של תוצאות החיפוש והיתרונות והחסרונות של מסלול חלופי. הוא יכול להכיל ציטוטים שמבוססים על אפס, כמו [0], שממופים לרשומות ב-results.
  • ‫results[]: רשימת המקומות שמוזכרים בסיכום, לפי דירוג. כל רשומה כוללת:
    • ‫place: פרטים על המקום:
      • ‫place: שם המשאב של המקום, בפורמט places/{id}.
      • ‫id: מזהה המקום. אפשר להשתמש בו עם ממשקי API אחרים של Google Maps Platform, למשל כדי להציג את המקום במפה.
      • ‫location: הקואורדינטות של קו הרוחב/האורך של המקום.
      • ‫googleMapsLinks: קישורים למפות Google למקום (placeUrl), מסלול (directionsUrl), ביקורות (reviewsUrl), תמונות (photosUrl) וכתיבת ביקורת (writeAReviewUrl).
      • ‫attribution: השיוך שצריך להציג עם המקום. דרישות ייחוס
    • ‫detourSummary: זמן ההגעה והמרחק הנוספים שנדרשים כדי לעצור במקום הזה לאורך המסלול:
      • ‫localizedDetourDistance: המרחק הנוסף בפורמט של שפת הבקשה, למשל "1.2 mi" או "1.9 km".
      • ‫detourDuration: זמן הנסיעה הנוסף כמחרוזת משך זמן, למשל "180s". השדה הזה לא מוגדר כשהמסלול מצוין באמצעות encoded_polyline.
  • ‫contentToken: אסימון להמחשה חזותית של נתונים באמצעות סוכן (גרסת טרום-השקה) שמאפשר להציג את המקומות בתשובה באמצעות Places UI Kit ללא עלות נוספת. מוחזר כשהתשובה כוללת לפחות מקום אחד.

לפרטים מלאים על השדות, עיינו בחומר העזר בנושא search_along_route.

חיוב ומכסות

כל בקשה של search_along_route היא אירוע אחד לחיוב במסגרת המק"ט Maps Grounding Pro. הגדרת include_extended_details לערך true או routing_preference לערך ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL לא מוסיפה חיובים. אם הנציג קורא קודם ל-compute_routes ואז מעביר את retrieval_token אל search_along_route, כל קריאה לכלי מחויבת כבקשה נפרדת.

אם אתם מציגים את המקומות מתשובה של search_along_route באמצעות Places UI Kit, אתם יכולים להשתמש בטוקן להצגה חזותית של נתונים מבוססי-סוכן (גרסת טרום-השקה) כדי שלא תחויבו על הבקשות האלה ל-Places UI Kit.

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