MCP Tools Reference: mapstools.googleapis.com

כלי: compute_routes

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

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

  1. ‫origin ו-destination (אובייקטים – חובה): צריך לספק כל אחד מהם באמצעות אחד מהאפשרויות הבאות:

    • address (מחרוזת, למשל 'Eiffel Tower, Paris'). מקומות עם שם, ציוני דרך ועסקים נפתרים ישירות, לכן אין צורך להפעיל קודם את search_places רק כדי להמיר כתובת של נקודת דרך לקואורדינטות. ציינו את העיר, האזור או המדינה שהמשתמש הזכיר.
    • ‫lat_lng (אובייקט, {"latitude": number, "longitude": number}).
    • place_id (מחרוזת, למשל 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), לדוגמה מ-search_places.

  2. intermediate_waypoints (מערך של אובייקטים – אופציונלי): עד 10 עצירות שצריך לעבור בהן, לפי הסדר, בין נקודת המוצא ליעד. אותו פורמט כמו origin. אין תמיכה ב-TRANSIT. לכלול רק עצירות שהמשתמש ביקש.

  3. ‫travel_mode (enum – אופציונלי): DRIVE (ברירת מחדל), WALK,‏ BICYCLE או TRANSIT.

  4. תזמון (אופציונלי – אפשר להגדיר לכל היותר אחד): חותמות זמן בפורמט RFC 3339 עם הפרש משעון UTC, למשל '2026-09-19T08:00:00-07:00'. ברירת המחדל היא יציאה עכשיו. בשדה TRANSIT, אפשר להזין תאריך עד 7 ימים בעבר או עד 100 ימים בעתיד. במצבים אחרים, אפשר להגדיר את השעה עד 365 ימים בעתיד, והיא לא יכולה להיות בעבר.

    • ‫departure_time: משתמשים בפרמטר הזה כשהמשתמש מציין מתי הוא ייצא (למשל, "מחר ב-8:00").
    • ‫arrival_time: משתמשים בפרמטר הזה כשהמשתמש מציין מתי הוא צריך להגיע (למשל, "להגיע עד 9:00").

  5. ‫routing_preference (enum – אופציונלי):

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

  6. location_bias (אובייקט – אופציונלי): {"latitude": number, "longitude": number} משמש להפגת עמימות של שמות מקומות בכתובות של נקודות דרך. אם השם לא חד-משמעי (למשל, "Springfield") והמשתמש לא ציין אזור, צריך להשאיר את השם כמו שהוא ב-address ולהגדיר את location_bias לאזור הרצוי במקום לנחש את האזור.

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

  8. include_polyline (בוליאני – אופציונלי): מגדירים את הערך true רק כשצריך את הגיאומטריה של המסלול (encoded_polyline). ברירת המחדל היא false.

הוראות לקריאה לפונקציה:

  • אם חסרה נקודת המוצא או נקודת היעד, חובה לבקש מהמשתמש הבהרה לפני שמפעילים את הכלי.
  • בשאלות כמו "מה המרחק בין א' לב'?", צריך להשתמש ב-ב' בתור origin וב-א' בתור destination.

דוגמה לקריאה לפונקציה: {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

הוראות לתשובה:

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

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

בקשת 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": "compute_routes",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

ComputeRoutesRequest.

ComputeRoutesRequest

ייצוג ב-JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  },
  "travelMode": enum (RouteTravelMode),
  "intermediateWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "routingPreference": enum (RoutingPreference),
  "locationBias": {
    object (LatLng)
  },
  "includePolyline": boolean,
  "computeAlternativeRoutes": boolean,

  // Union field timing can be only one of the following:
  "departureTime": string,
  "arrivalTime": string
  // End of list of possible types for union field timing.
}
שדות
origin

object (Waypoint)

חובה. ציון דרך של המוצא.
destination

object (Waypoint)

חובה. נקודת ציון של היעד.
travelMode

enum (RouteTravelMode)

אופציונלי. מציין את אמצעי התחבורה.
intermediateWaypoints[]

object (Waypoint)

אופציונלי. תחנות ביניים בין נקודת המוצא ליעד שצריך לעבור בהן לפי הסדר. אפשר להוסיף עד 10 נקודות ציון ביניים. אין תמיכה בנקודות ביניים במסלול כשהערך של travel_mode הוא TRANSIT.
routingPreference

enum (RoutingPreference)

אופציונלי. קובע איך נתוני התנועה משמשים לחישוב המסלול. אין תמיכה ב-ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL כשהערך של travel_mode הוא WALK או BICYCLE. ב-TRANSIT, הוא מאפשר לקבל נתוני תחבורה ציבורית בזמן אמת, כמו עיכובים וביטולים.
locationBias

object (LatLng)

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

boolean

אופציונלי. אם לכלול את הקו הפוליגוני המקודד במסלולים שבתשובה. ברירת המחדל היא false. כשהערך הוא true, מוחזר הערך Route.encoded_polyline.
computeAlternativeRoutes

boolean

אופציונלי. אם לחשב מסלולים חלופיים בנוסף למסלול המומלץ. ברירת המחדל היא false, ובמקרה כזה מוחזר רק המסלול המומלץ. כשהערך מוגדר כ-true, מוחזרים כל המסלולים הזמינים, אבל יכול להיות שלא יהיו חלופות לכל בקשה.
שדה של איחוד timing. מציינת מתי לצאת מנקודת המוצא או מתי להגיע לנקודת הציון האחרונה. אם לא מציינים ערך, ברירת המחדל היא יציאה בזמן הנוכחי. בשדה TRANSIT, הזמן חייב להיות עד 7 ימים בעבר ועד 100 ימים בעתיד. באמצעי תחבורה אחרים, הזמן לא יכול להיות בעבר, והוא יכול להיות עד 365 ימים בעתיד. הערך timing יכול להיות רק אחד מהבאים:
departureTime

string (Timestamp format)

אופציונלי. מציין שצריך לחשב את המסלול על סמך שעת היציאה.

השימוש הוא ב-RFC 3339, שבו הפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. לדוגמה: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
arrivalTime

string (Timestamp format)

אופציונלי. מציין שצריך לחשב את המסלול על סמך זמן ההגעה.

השימוש הוא ב-RFC 3339, שבו הפלט שנוצר תמיד יהיה מנורמל ל-Z וישתמש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. לדוגמה: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

חותמת זמן

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

string (int64 format)

מייצג שניות של זמן UTC מאז ראשית זמן יוניקס (Unix epoch) ‏1970-01-01T00:00:00Z. הערך חייב להיות בין ‎-62135596800 ל-253402300799, כולל (טווח שמתאים ל-‎0001-01-01T00:00:00Z עד ‎9999-12-31T23:59:59Z).
nanos

integer

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

נקודת ציון

ייצוג ב-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].

RouteTravelMode

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

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

RoutingPreference

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

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

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

הערך הזה יפעיל את רמת Pro ויגרום לעלות חיוב גבוהה יותר ולזמן אחזור ארוך יותר. האפשרות הזו זמינה רק ללקוחות שנוספו לרשימת ההיתרים. אם הוא לא ברשימת ההיתרים, הבקשה תוחזר ל-ROUTING_PREFERENCE_TRAFFIC_UNAWARE.

סכימת הפלט

‫ComputeRoutesResponse.

ComputeRoutesResponse

ייצוג ב-JSON 
{
  "routes": [
    {
      object (Route)
    }
  ]
}
שדות
routes[]

object (Route)

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

נתיב

ייצוג ב-JSON 
{
  "distanceMeters": integer,
  "duration": string,
  "attribution": {
    object (Attribution)
  },
  "encodedPolyline": string,
  "retrievalToken": string
}
שדות
distanceMeters

integer

מרחק הנסיעה של המסלול, במטרים.
duration

string (Duration format)

משך הזמן שנדרש כדי לנווט במסלול.

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

object (Attribution)

השיוך שחובה להציג עם המסלול.
encodedPolyline

string

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

string

טוקן שאפשר להשתמש בו כדי לאחזר את המסלול הספציפי הזה בכלים במורד הזרם, כמו SearchAlongRoute. הקוד תקף ל-10 דקות.

משך

ייצוג ב-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, כולל.

שיוך (Attribution)

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

string

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

string

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

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

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

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

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

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