MCP Tools Reference: mapstools.googleapis.com

כלי: search_along_route

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

דרישות קלט (קריטי):

  1. text_query (מחרוזת – חובה): תיאור בשפה טבעית של מה שרוצים לחפש לאורך המסלול.

    • לדוגמה: 'ev chargers',‏ 'coffee',‏ 'vegetarian restaurants',‏ 'rest stops'.

  2. מפרט המסלול (חובה – צריך לספק בדיוק אחת מהאפשרויות הבאות):

    • ‫retrieval_token (מחרוזת): הערך של retrieval_token שהוחזר על ידי קריאה קודמת של compute_routes למסלול DRIVE. עדיף להשתמש בזה בכל פעם שהמסלול כבר חושב. האסימון תקף למשך 10 דקות.
    • route_endpoints (אובייקט): ה-origin וה-destination של המסלול. צריך לספק כל אחד מהם באמצעות אחת מהאפשרויות הבאות: address,‏ lat_lng או place_id.
      • לדוגמה: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • ‫encoded_polyline (מחרוזת): קו פוליגוני מקודד שמייצג מסלול של DRIVE.

  3. ‫travel_mode (enum – אופציונלי): DRIVE (ברירת מחדל), WALK או BICYCLE. האפשרויות WALK ו-BICYCLE נתמכות רק עם route_endpoints. אין תמיכה ב-TRANSIT.

  4. routing_preference (enum - OPTIONAL):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (ברירת המחדל): חישוב המסלול ודרכים חלופיות בלי עדכוני תנועה בזמן אמת. זמן האחזור הכי קצר.
    • ‫ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: משתמש במצב התנועה בזמן אמת, אם הוא זמין. הפעולה הזו לא נתמכת ב-WALK או ב-BICYCLE. צריך להגדיר את זה רק כשהמשתמש שואל על עומסי תנועה או על זמני נסיעה בדרכים חלופיות בהתאם לעומסי התנועה. הוא גורם לזמן אחזור ארוך יותר.

  5. ‫include_extended_details (בוליאני – אופציונלי): צריך להגדיר את הערך true רק כשהבקשה דורשת תובנות איכותיות, פריטים או מבצעים ספציפיים בתפריט, אווירה, טיפים למבקרים או רמת עומס, זמינות של מטען לרכב חשמלי, מחירי דלק או פרטים איכותיים עשירים אחרים. ברירת המחדל היא false. הפעלת ההגדרה הזו עלולה להאריך את זמן האחזור.

  6. ‫language_code (מחרוזת – אופציונלי): השפה של סיכום התוצאות ופרטי המקום, למשל en,‏ ja,‏ en-US. ברירת המחדל היא en-US.

  7. region_code (מחרוזת – אופציונלי): קוד האזור של המשתמש לפי Unicode CLDR, למשל US,‏ CA.

הוראות לקריאת API לכלי:

  • כל תוצאה כוללת detour_summary (אם זמין) שמתאר את המרחק הנוסף (localized_detour_distance) ואת הזמן הנוסף (detour_duration) שיידרש כדי לעצור במקום הזה, אלא אם המסלול ניתן בתור encoded_polyline. אפשר להשתמש בו כדי להשוות בין אפשרויות.
  • התשובה summary עשויה להכיל ציטוטים שמבוססים על אפס (למשל, "[0]") שמפנים לרשומות ב-results.
  • הפלט המבוסס-קרקע חייב להיות משויך למקור באמצעות השדה attribution של כל results[].place, אם הוא זמין.

בדוגמת הקוד הבאה מוסבר איך להשתמש ב-curl כדי להפעיל את כלי ה-MCP‏ search_along_route.

בקשת Curl 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

הודעת בקשה ל-SearchAlongRoute.

SearchAlongRouteRequest

ייצוג ב-JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "routingPreference": enum (RoutingPreference),
  "includeExtendedDetails": boolean,
  "travelMode": enum (RouteTravelMode),

  // Union field route_spec can be only one of the following:
  "encodedPolyline": string,
  "retrievalToken": string,
  "routeEndpoints": {
    object (RouteEndpoints)
  }
  // End of list of possible types for union field route_spec.
}
שדות
textQuery

string

חובה. שאילתת חיפוש בשפה טבעית (למשל, "מטענים לרכב חשמלי", "קפה").
languageCode

string

זה שינוי אופציונלי. השפה של הסיכום ופרטי המקום. ברירת המחדל היא "en-US".
regionCode

string

זה שינוי אופציונלי. קוד המדינה או האזור (CLDR) של המיקום (למשל, "US").
routingPreference

enum (RoutingPreference)

זה שינוי אופציונלי. העדפת מסלול אופציונלית שמציינת איך להשתמש בנתוני התנועה. ברירת המחדל היא TRAFFIC_UNAWARE.
includeExtendedDetails

boolean

זה שינוי אופציונלי. כולל פרטי מקום מורחבים בתשובה.

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

משאירים את הערך false (ברירת המחדל) לחיפושים רגילים (למשל, סוגי מטבחים, סוגי חנויות), חיפושי מיקום/כתובת, פרטים ליצירת קשר, שעות פעילות ומטא-נתונים/שירותים רגילים.

הפעלת השדה הזה עלולה לגרום לזמן אחזור ארוך יותר.
travelMode

enum (RouteTravelMode)

זה שינוי אופציונלי. מציין את אופן הנסיעה שמשמש לחישוב המסלול ודרכי המעקף. ברירת המחדל היא DRIVE. האפשרויות WALK ו-BICYCLE נתמכות רק עם route_endpoints. אין תמיכה ב-TRANSIT.
שדה של איחוד route_spec. מפרט המסלול: מסלול קיים, אסימון מסלול או נקודות קצה של מוצא/יעד. הערך route_spec יכול להיות רק אחד מהבאים:
encodedPolyline

string

מחרוזת של קו פוליגוני מקודד שמייצגת את המסלול. מידע נוסף זמין בכתובת https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

אסימון אחזור שהוחזר מקריאה קודמת של ComputeRoutes שמייצגת את המסלול.
routeEndpoints

object (RouteEndpoints)

נקודות קצה מפורשות של המסלול (מוצא ויעד).

RouteEndpoints

ייצוג ב-JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
שדות
origin

object (Waypoint)

חובה. נקודת ההתחלה (כתובת, מזהה מקום או קואורדינטות גיאוגרפיות).
destination

object (Waypoint)

חובה. נקודת היעד (כתובת, מזהה מקום או קואורדינטות גיאוגרפיות).

נקודת ציון

ייצוג ב-JSON 
{

  // Union field location_type can be only one of the following:
  "latLng": {
    object (LatLng)
  },
  "placeId": string,
  "address": string
  // End of list of possible types for union field location_type.
}
שדות
שדה של איחוד location_type. דרכים שונות לייצג מיקום. הערך location_type יכול להיות רק אחד מהבאים:
latLng

object (LatLng)

נקודה שצוינה באמצעות קואורדינטות גיאוגרפיות.
placeId

string

מזהה המקום שמשויך לנקודת הדרך.
address

string

כתובת קריאה לאנשים או Plus Code. פרטים נוספים זמינים בכתובת https://plus.codes.

LatLng

ייצוג ב-JSON 
{
  "latitude": number,
  "longitude": number
}
שדות
latitude

number

קו הרוחב במעלות. הוא חייב להיות בטווח [‎-90.0, +90.0].
longitude

number

קו האורך במעלות. הוא חייב להיות בטווח [‎-180.0, +180.0].

RoutingPreference

קבוצת ערכים שמציינים גורמים שצריך להביא בחשבון כשמחשבים את המסלול.

טיפוסים בני מנייה (enum)
ROUTING_PREFERENCE_UNSPECIFIED לא צוינה העדפת ניתוב. ברירת המחדל היא ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE חישוב מסלולים בלי להתחשב במצב התנועה בזמן אמת. מתאים כשמצב התנועה לא משנה או לא רלוונטי. השימוש בערך הזה מניב את זמן האחזור הנמוך ביותר.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

מחשב מסלולים תוך התחשבות במצב התנועה בזמן אמת, כשנתוני התנועה זמינים. ב-TRANSIT, המערכת משתמשת בנתוני תחבורה ציבורית בזמן אמת, כמו עיכובים וביטולים, כשהם זמינים.

הערך הזה יפעיל את רמת Pro, ויגרום לעלייה בעלות החיוב ובזמן האחזור.

RouteTravelMode

קבוצת ערכים שמשמשת לציון אופן הנסיעה.

טיפוסים בני מנייה (enum)
ROUTE_TRAVEL_MODE_UNSPECIFIED לא צוין מצב נסיעה. ברירת המחדל היא DRIVE.
DRIVE נסיעה ברכב פרטי.
WALK הליכה. הערה: מסלולי WALK נמצאים בגרסת בטא, ולפעמים חסרים בהם מדרכות או שבילים להולכי רגל. חובה להציג את האזהרה הזו למשתמש בכל מסלול הליכה שמוצג באפליקציה.
BICYCLE נסיעה באופניים.
TRANSIT נסיעה בתחבורה ציבורית.

סכימת הפלט

הודעת תגובה ל-SearchAlongRoute.

SearchAlongRouteResponse

ייצוג ב-JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
שדות
results[]

object (Result)

פלט בלבד. רשימה מדורגת של תוצאות החיפוש שנמצאו לאורך המסלול.
summary

string

פלט בלבד. סיכום בשפה טבעית של תוצאות החיפוש והיתרונות והחסרונות של מסלולים חלופיים. יכול להכיל ציטוטים שמבוססים על אפס (למשל, "[0]",‏ "[1]") שמפנים לרשומות התואמות ברשימה results.
contentToken

string

פלט בלבד. טוקן מוצפן שמכיל את ההקשר של החיפוש ואפשר להעביר אותו לשירותי רינדור חזותי של מפות Google, לערכות SDK או לערכת הכלים לסוכן AI ב-Maps‏ (A2UI) כדי להציג רכיבים אינטראקטיביים של ממשק המשתמש לתוצאות החיפוש שהוחזרו.

תוצאה

ייצוג ב-JSON 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
שדות
place

object (PlaceView)

פלט בלבד. פרטים על המקום שנמצא לאורך המסלול.
detourSummary

object (DetourSummary)

פלט בלבד. מדדי סטייה מהמסלול שנובעים מהוספת המקום הזה כתחנת ביניים לאורך המסלול. השדה מושמט או ריק אם לא ניתן לחשב את מדדי העיקוף.

PlaceView

ייצוג ב-JSON 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },
  "attribution": {
    object (Attribution)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (LatLng)
  }
  // End of list of possible types for union field _location.
}
שדות
place

string

שם המשאב של המקום הבסיסי, בפורמט "places/{id}".
id

string

מזהה המקום של המקום הבסיסי.
googleMapsLinks

object (GoogleMapsLinks)

קישורים להפעלת פעולות שונות במפות Google.
attribution

object (Attribution)

השיוך הנדרש שיוצג עם המקום.

שדה של איחוד _location.

הערך _location יכול להיות רק אחד מהבאים:
location

object (LatLng)

המיקום של המקום הזה.

LatLng

ייצוג ב-JSON 
{
  "latitude": number,
  "longitude": number
}
שדות
latitude

number

קו הרוחב במעלות. הוא חייב להיות בטווח [‎-90.0, +90.0].
longitude

number

קו האורך במעלות. הוא חייב להיות בטווח [‎-180.0, +180.0].
ייצוג ב-JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
שדות
directionsUrl

string

קישור להצגת מסלול ההגעה למקום. הקישור מאכלס רק את מיקום היעד ומשתמש במצב הנסיעה שמוגדר כברירת מחדל DRIVE.
placeUrl

string

קישור להצגת המקום הזה.
writeAReviewUrl

string

קישור לכתיבת ביקורת על המקום הזה במפות Google.
reviewsUrl

string

קישור להצגת ביקורות על המקום הזה במפות Google.
photosUrl

string

קישור להצגת תמונות של המקום הזה במפות Google.

שיוך (Attribution)

ייצוג ב-JSON 
{
  "title": string,
  "url": string
}
שדות
title

string

הכותרת שתוצג בשיוך (Attribution).
url

string

כתובת ה-URL של הקישור לשיוך.

DetourSummary

ייצוג ב-JSON 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
שדות
detourDuration

string (Duration format)

זמן הנסיעה הנוסף שנדרש כדי לסטות מהמסלול הראשי אל המקום הזה. הערך הזה לא מוגדר אם המסלול צוין על ידי encoded_polyline.

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-"s". לדוגמה: "3.5s".
localizedDetourDistance

string

המרחק הנוסף שצריך לעבור כדי להגיע למקום הזה מהמסלול הראשי, בפורמט שמתאים להצגה בשפת הבקשה (למשל "‎1.2 mi" או "‎1,9 km").

משך

ייצוג ב-JSON 
{
  "seconds": string,
  "nanos": integer
}
שדות
seconds

string (int64 format)

שניות חתומות של משך הזמן. הערך חייב להיות בין ‎-315,576,000,000 ל-‎+315,576,000,000, כולל. הערה: הגבולות האלה מחושבים לפי: 60 שניות/דקה * 60 דקות/שעה * 24 שעות/יום * 365.25 ימים/שנה * 10,000 שנים
nanos

integer

שברים חתומים של שנייה ברזולוציה של ננו-שנייה של משך הזמן. משכי זמן של פחות משנייה מיוצגים על ידי שדה seconds עם הערך 0 ושדה nanos עם ערך חיובי או שלילי. במשכי זמן של שנייה אחת או יותר, ערך שאינו אפס בשדה nanos חייב להיות עם אותו סימן כמו השדה seconds. הערך חייב להיות בין ‎-999,999,999 ל-‎+999,999,999, כולל.

הערות לגבי הכלים

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

בנוסף למחרוזת הכותרת, הרמזים הבוליאניים הבאים מוגדרים כך:

  • ‫readOnlyHint: אם הערך הוא True, הכלי לא משנה את הסביבה שלו. ברירת המחדל: false.
  • ‫destructiveHint: אם הערך הוא True, הכלי יכול לבצע פעולות הרסניות. אם הערך הוא False, הכלי יכול לבצע רק פעולות הוספה. ברירת המחדל: true.
  • ‫idempotentHint: אם הערך הוא True, קריאה חוזרת לכלי עם אותם ארגומנטים לא תשפיע על הסביבה שלו. ברירת המחדל: false.
  • ‫openWorldHint: אם הערך הוא True, הכלי יכול לקיים אינטראקציה עם "עולם פתוח" של ישויות חיצוניות. אם הערך הוא false, הכלי יכול לקיים אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי חיפוש באינטרנט הוא כלי בעולם פתוח, אבל כלי זיכרון הוא לא כלי בעולם פתוח.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌