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 (字串)：先前 compute_routes 呼叫 DRIVE 路徑時傳回的 retrieval_token。如果路線已計算完畢，建議優先使用這個方法。權杖的有效期限為 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 (列舉 - 選用)：DRIVE (預設)、WALK 或 BICYCLE。WALK 和 BICYCLE 僅支援 route_endpoints。不支援 TRANSIT。

  4. routing_preference (列舉 - 選用)：

    • 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。

工具呼叫操作說明：

  • 每項結果都包含 detour_summary (如有)，說明在該地點停留所產生的額外距離 (localized_detour_distance) 和額外時間 (detour_duration) (除非路線指定為 encoded_polyline)。可用來比較不同選項。
  • 回覆 summary 可能包含從零開始的引用 (例如「[0]」)，參照 results 中的項目。
  • 建立基準的輸出內容必須歸因於來源，並在可用時使用每個 results[].place 的 attribution 欄位。

下列程式碼範例說明如何使用 curl 呼叫 search_along_route MCP 工具。

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)

必填。起點 (地址、地點 ID 或地理座標)。
destination

object (Waypoint)

必填。目的地點 (地址、地點 ID 或地理座標)。

途經點

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

與路線控點相關聯的地點 ID。
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

一組值，指定計算路線時要考量的因素。

列舉
ROUTING_PREFERENCE_UNSPECIFIED 未指定轉送偏好設定。預設值為 ROUTING_PREFERENCE_TRAFFIC_UNAWARE。
ROUTING_PREFERENCE_TRAFFIC_UNAWARE 計算路線時不考慮即時路況。適合路況不重要或不適用的情況。使用這個值可達到最低延遲時間。
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

在有車流量資料的情況下，計算路線時會考量即時路況。TRANSIT：使用即時大眾運輸資料 (如有)，例如誤點和取消資訊。

這個值會觸發 Pro 級別，並產生較高的已計費用和延遲時間。

RouteTravelMode

一組用於指定交通方式的值。

列舉
ROUTE_TRAVEL_MODE_UNSPECIFIED 未指定交通工具。預設值為 DRIVE。
DRIVE 搭乘客車。
WALK 步行。注意：WALK路線目前為 Beta 版，有時可能無法明確提供人行道或行人步道。只要應用程式顯示步行路線，就必須向使用者顯示這則警告。
BICYCLE 騎單車。
TRANSIT 搭乘大眾運輸工具。

輸出內容的結構定義

SearchAlongRoute 的回應訊息。

SearchAlongRouteResponse

JSON 表示法 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
欄位
results[]

object (Result)

僅供輸出。沿途搜尋結果的排名清單。
summary

string

僅供輸出。以自然語言摘要搜尋結果和繞道取捨。可能包含從零開始的引用 (例如「[0]」、「[1]」)，參照 results 清單中的對應項目。
contentToken

string

僅供輸出。加密權杖，封裝搜尋情境，可傳遞至 Google 地圖視覺算繪服務、SDK 或地圖代理 UI 工具包 (A2UI)，為傳回的搜尋結果顯示互動式 UI 元件。

結果

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

基礎地點的地點 ID。
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 地圖上這個地點的相片。

歸因

JSON 表示法 
{
  "title": string,
  "url": string
}
欄位
title

string

要顯示的出處標題。
url

string

要連結至出處的網址。

DetourSummary

JSON 表示法 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
欄位
detourDuration

string (Duration format)

從主要路線繞道至這個地點所需的額外行程時間。如果路徑是由 encoded_polyline 指定，則不會設定這個值。

以秒為單位的時間長度，最多 9 個小數位數，結尾為「s」。例如："3.5s"。
localizedDetourDistance

string

從主要路線繞道至這個地點所需的額外距離，格式會依要求語言顯示 (例如「1.2 英里」或「1.9 公里」)。

時間長度

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
欄位
seconds

string (int64 format)

時間範圍的有號秒數。必須介於 -315,576,000,000 至 +315,576,000,000 之間 (含)。注意：這些界限的計算方式為：60 秒/分鐘 * 60 分鐘/小時 * 24 小時/天 * 365.25 天/年 * 10000 年
nanos

integer

時間範圍內以奈秒解析度表示的有正負號秒數分數。如果時間長度不到一秒，則會以 0 seconds 欄位和正或負 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: ❌