MCP Tools Reference: mapstools.googleapis.com

Công cụ: search_along_route

Gọi công cụ này khi người dùng muốn tìm địa điểm, doanh nghiệp hoặc điểm tham quan dọc theo tuyến đường du lịch (ví dụ: "trạm xăng trên đường đến Tahoe", "quán cà phê giữa San Francisco và San Jose"). Việc gọi công cụ này sẽ tốn nhiều chi phí hơn so với search_places, vì vậy, hãy sử dụng search_places khi tìm kiếm gần một vị trí thay vì dọc theo một tuyến đường.

Yêu cầu về dữ liệu đầu vào (QUAN TRỌNG):

  1. text_query (chuỗi – BẮT BUỘC): Nội dung mô tả bằng ngôn ngữ tự nhiên về những gì cần tìm dọc theo tuyến đường.

    • Ví dụ: 'ev chargers', 'coffee', 'vegetarian restaurants', 'rest stops'.

  2. Quy cách tuyến đường (BẮT BUỘC – cung cấp chính xác MỘT trong các thông tin sau):

    • retrieval_token (chuỗi): retrieval_token được trả về từ lệnh gọi compute_routes trước đó cho tuyến DRIVE. Ưu tiên sử dụng phương thức này bất cứ khi nào tuyến đường đã được tính toán. Mã thông báo này có hiệu lực trong 10 phút.
    • route_endpoints (đối tượng): origin và destination của tuyến đường. Bạn phải cung cấp từng thuộc tính bằng một trong các thuộc tính address, lat_lng hoặc place_id.
      • Ví dụ: {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline (chuỗi): Một hình nhiều đường được mã hoá đại diện cho một tuyến đường DRIVE.

  3. travel_mode (enum – KHÔNG BẮT BUỘC): DRIVE (mặc định), WALK hoặc BICYCLE. WALK và BICYCLE chỉ được hỗ trợ với route_endpoints. TRANSIT không được hỗ trợ.

  4. routing_preference (enum – KHÔNG BẮT BUỘC):

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (mặc định): tính toán tuyến đường và đường vòng mà không có thông tin giao thông theo thời gian thực. Độ trễ thấp nhất.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: sử dụng tình trạng giao thông trực tiếp khi có. Không hỗ trợ WALK hoặc BICYCLE. CHỈ đặt tham số này khi người dùng hỏi về tình hình giao thông, tình trạng tắc nghẽn hoặc thời gian đi đường vòng đã điều chỉnh theo tình hình giao thông. Độ trễ cao hơn.

  5. include_extended_details (boolean – KHÔNG BẮT BUỘC): Chỉ đặt thành true khi yêu cầu cần có thông tin chi tiết về bài đánh giá định tính, các món trong thực đơn hoặc sản phẩm/dịch vụ, bầu không khí, mẹo hoặc mức độ đông đúc của khách truy cập, tình trạng còn chỗ của bộ sạc xe điện, giá xăng hoặc các thông tin chi tiết định tính phong phú khác. Giá trị mặc định là false. Việc bật tính năng này có thể làm tăng độ trễ.

  6. language_code (chuỗi – KHÔNG BẮT BUỘC): Ngôn ngữ cho thông tin tóm tắt về kết quả và thông tin chi tiết về địa điểm, ví dụ: en, ja, en-US. Giá trị mặc định là en-US.

  7. region_code (chuỗi – KHÔNG BẮT BUỘC): Mã khu vực CLDR Unicode của người dùng, ví dụ: US, CA.

Hướng dẫn về lệnh gọi công cụ:

  • Mỗi kết quả bao gồm một detour_summary (nếu có) mô tả quãng đường tăng thêm (localized_detour_distance) và thời gian tăng thêm (detour_duration) do dừng lại ở địa điểm đó, trừ phi tuyến đường được cung cấp dưới dạng encoded_polyline. Hãy dùng tính năng này để so sánh các lựa chọn.
  • Câu trả lời summary có thể chứa các trích dẫn dựa trên số 0 (ví dụ: "[0]") tham chiếu đến các mục trong results.
  • Kết quả dựa trên dữ liệu thực tế phải được ghi nhận cho nguồn bằng cách sử dụng trường attribution của mỗi results[].place (nếu có).

Mã mẫu sau đây cho biết cách sử dụng curl để gọi công cụ MCP search_along_route.

Yêu cầu 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
}'

Giản đồ đầu vào

Thông báo yêu cầu cho SearchAlongRoute.

SearchAlongRouteRequest

Biểu diễn dưới dạng 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.
}
Trường
textQuery

string

Bắt buộc. Cụm từ tìm kiếm bằng ngôn ngữ tự nhiên (ví dụ: "bộ sạc xe điện", "cà phê").
languageCode

string

Không bắt buộc. Ngôn ngữ cho bản tóm tắt và Place Details. Giá trị mặc định là "en-US".
regionCode

string

Không bắt buộc. Mã quốc gia/khu vực (CLDR) của vị trí (ví dụ: "US").
routingPreference

enum (RoutingPreference)

Không bắt buộc. Lựa chọn ưu tiên về định tuyến (không bắt buộc) chỉ định cách sử dụng dữ liệu lưu lượng truy cập. Giá trị mặc định là TRAFFIC_UNAWARE.
includeExtendedDetails

boolean

Không bắt buộc. Bao gồm thông tin chi tiết mở rộng về Place Details trong phản hồi.

Đặt trường này thành true khi yêu cầu của người dùng cần có thông tin chi tiết định tính phong phú, thông tin linh động theo thời gian thực hoặc thuộc tính thực thể chuyên biệt: – Bài đánh giá định tính, cảm nhận của khách hàng và ý kiến phản hồi. – Các sản phẩm/dịch vụ cụ thể như món trong thực đơn, món ăn, món đặc sản, đồ uống hoặc điểm nổi bật của doanh nghiệp. – Bầu không khí, phong cách trang trí nội thất, tính thẩm mỹ, không gian hoặc tâm trạng chất lượng. – Dữ liệu theo thời gian thực và thông số kỹ thuật của cơ sở chuyên khoa, chính sách/mẹo dành cho khách, thời gian chờ.

Để trống false (mặc định) cho các lượt tìm kiếm thông thường (ví dụ: ẩm thực, loại cửa hàng), lượt tra cứu vị trí/địa chỉ, thông tin liên hệ, giờ hoạt động và siêu dữ liệu/tiện nghi tiêu chuẩn.

Việc bật trường này có thể làm tăng độ trễ.
travelMode

enum (RouteTravelMode)

Không bắt buộc. Chỉ định phương tiện di chuyển dùng để tính toán tuyến đường và đường vòng. Giá trị mặc định là DRIVE. WALK và BICYCLE chỉ được hỗ trợ với route_endpoints. TRANSIT không được hỗ trợ.
Trường nhóm route_spec. Thông số kỹ thuật của tuyến đường: tuyến đường hiện có, mã thông báo tuyến đường hoặc điểm cuối của điểm xuất phát/điểm đến. route_spec chỉ có thể là một trong những trạng thái sau:
encodedPolyline

string

Một chuỗi hình nhiều đường được mã hoá đại diện cho tuyến đường. Xem https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

Mã truy xuất được trả về từ lệnh gọi ComputeRoutes trước đó đại diện cho tuyến đường.
routeEndpoints

object (RouteEndpoints)

Điểm cuối của tuyến đường rõ ràng (điểm xuất phát và điểm đến).

RouteEndpoints

Biểu diễn dưới dạng JSON 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
Trường
origin

object (Waypoint)

Bắt buộc. Điểm xuất phát (địa chỉ, Mã địa điểm hoặc toạ độ địa lý).
destination

object (Waypoint)

Bắt buộc. Điểm đến (địa chỉ, Mã địa điểm hoặc toạ độ địa lý).

Waypoint

Biểu diễn dưới dạng 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.
}
Trường
Trường nhóm location_type. Các cách khác nhau để thể hiện một vị trí. location_type chỉ có thể là một trong những trạng thái sau:
latLng

object (LatLng)

Một điểm được chỉ định bằng toạ độ địa lý.
placeId

string

Mã địa điểm liên kết với điểm tham chiếu.
address

string

Địa chỉ mà con người có thể đọc được hoặc mã cộng. Hãy xem https://plus.codes để biết thông tin chi tiết.

LatLng

Biểu diễn dưới dạng JSON 
{
  "latitude": number,
  "longitude": number
}
Trường
latitude

number

Vĩ độ tính bằng độ. Giá trị này phải nằm trong khoảng [-90,0, +90,0].
longitude

number

Kinh độ tính bằng độ. Giá trị này phải nằm trong khoảng [-180,0, +180,0].

RoutingPreference

Một tập hợp các giá trị chỉ định các yếu tố cần xem xét khi tính toán tuyến đường.

Enum
ROUTING_PREFERENCE_UNSPECIFIED Chưa chỉ định lựa chọn ưu tiên về định tuyến. Giá trị mặc định là ROUTING_PREFERENCE_TRAFFIC_UNAWARE.
ROUTING_PREFERENCE_TRAFFIC_UNAWARE Tính toán tuyến đường mà không xem xét tình trạng giao thông trực tiếp. Phù hợp khi tình trạng giao thông không quan trọng hoặc không áp dụng. Việc sử dụng giá trị này sẽ tạo ra độ trễ thấp nhất.
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

Tính toán tuyến đường dựa trên tình trạng giao thông trực tiếp (khi có dữ liệu giao thông). Đối với TRANSIT, sử dụng dữ liệu về phương tiện công cộng theo thời gian thực, chẳng hạn như tình trạng trễ giờ và huỷ chuyến, nếu có.

Giá trị này sẽ kích hoạt cấp Pro và làm tăng chi phí thanh toán cũng như độ trễ.

RouteTravelMode

Một tập hợp các giá trị dùng để chỉ định phương thức di chuyển.

Enum
ROUTE_TRAVEL_MODE_UNSPECIFIED Chưa chỉ định phương thức di chuyển. Giá trị mặc định là DRIVE.
DRIVE Đi bằng xe chở khách.
WALK Đi bộ. LƯU Ý: Các tuyến đường dành cho WALK đang trong giai đoạn thử nghiệm và đôi khi có thể thiếu vỉa hè hoặc lối đi rõ ràng cho người đi bộ. Bạn phải hiển thị cảnh báo này cho người dùng đối với tất cả thông tin về đường đi bộ mà bạn hiển thị trong ứng dụng.
BICYCLE Đi bằng xe đạp.
TRANSIT Đi bằng phương tiện công cộng.

Giản đồ đầu ra

Thông báo phản hồi cho SearchAlongRoute.

SearchAlongRouteResponse

Biểu diễn dưới dạng JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
Trường
results[]

object (Result)

Chỉ có đầu ra. Danh sách kết quả tìm kiếm được xếp hạng dọc theo tuyến đường.
summary

string

Chỉ có đầu ra. Tóm tắt kết quả tìm kiếm và các lựa chọn thay thế bằng ngôn ngữ tự nhiên. Có thể chứa các trích dẫn dựa trên số 0 (ví dụ: "[0]", "[1]") tham chiếu đến các mục tương ứng trong danh sách results.
contentToken

string

Chỉ có đầu ra. Một mã thông báo đã mã hoá, chứa bối cảnh tìm kiếm và có thể được truyền đến các dịch vụ kết xuất hình ảnh, SDK của Google Maps hoặc Maps Agentic UI Toolkit (A2UI) để hiển thị các thành phần giao diện người dùng tương tác cho kết quả tìm kiếm được trả về.

Kết quả

Biểu diễn dưới dạng JSON 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
Trường
place

object (PlaceView)

Chỉ có đầu ra. Thông tin chi tiết về địa điểm tìm thấy dọc theo tuyến đường.
detourSummary

object (DetourSummary)

Chỉ có đầu ra. Các chỉ số về đường vòng phát sinh khi thêm địa điểm này làm điểm dừng trung gian dọc theo tuyến đường. Bỏ qua hoặc để trống nếu không thể tính toán chỉ số đường vòng.

PlaceView

Biểu diễn dưới dạng 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.
}
Trường
place

string

Tên tài nguyên của địa điểm cơ bản, ở định dạng "places/{id}".
id

string

Mã địa điểm của địa điểm cơ bản.
googleMapsLinks

object (GoogleMapsLinks)

Đường liên kết để kích hoạt các hành động khác nhau trên Google Maps.
attribution

object (Attribution)

Thông tin ghi nhận tác giả bắt buộc phải hiển thị cùng với địa điểm.

Trường nhóm _location.

_location chỉ có thể là một trong những trạng thái sau:
location

object (LatLng)

Vị trí của địa điểm này.

LatLng

Biểu diễn dưới dạng JSON 
{
  "latitude": number,
  "longitude": number
}
Trường
latitude

number

Vĩ độ tính bằng độ. Giá trị này phải nằm trong khoảng [-90,0, +90,0].
longitude

number

Kinh độ tính bằng độ. Giá trị này phải nằm trong khoảng [-180,0, +180,0].
Biểu diễn dưới dạng JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Trường
directionsUrl

string

Đường liên kết để hiện đường đi đến địa điểm. Đường liên kết này chỉ điền sẵn vị trí của điểm đến và sử dụng phương tiện di chuyển mặc định DRIVE.
placeUrl

string

Đường liên kết để hiển thị địa điểm này.
writeAReviewUrl

string

Một đường liên kết để viết bài đánh giá về địa điểm này trên Google Maps.
reviewsUrl

string

Đường liên kết để xem các bài đánh giá về địa điểm này trên Google Maps.
photosUrl

string

Đường liên kết để xem ảnh về địa điểm này trên Google Maps.

Phân bổ

Biểu diễn dưới dạng JSON 
{
  "title": string,
  "url": string
}
Trường
title

string

Tiêu đề sẽ hiển thị cho thông tin ghi nhận tác giả.
url

string

URL để liên kết đến thông tin ghi nhận tác giả.

DetourSummary

Biểu diễn dưới dạng JSON 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
Trường
detourDuration

string (Duration format)

Thời gian di chuyển cần thêm để rẽ vào địa điểm này từ tuyến đường chính. Giá trị này không được đặt nếu tuyến đường được chỉ định bằng encoded_polyline.

Thời lượng tính bằng giây, có tối đa 9 chữ số thập phân, kết thúc bằng "s". Ví dụ: "3.5s".
localizedDetourDistance

string

Khoảng cách bổ sung cần thiết để đi đường vòng đến địa điểm này từ tuyến đường chính, được định dạng để hiển thị bằng ngôn ngữ yêu cầu (ví dụ: "1,2 dặm" hoặc "1,9 km").

Thời lượng

Biểu diễn dưới dạng JSON 
{
  "seconds": string,
  "nanos": integer
}
Trường
seconds

string (int64 format)

Số giây có dấu của khoảng thời gian. Phải nằm trong khoảng từ -315.576.000.000 đến +315.576.000.000. Lưu ý: các giới hạn này được tính từ: 60 giây/phút * 60 phút/giờ * 24 giờ/ngày * 365,25 ngày/năm * 10.000 năm
nanos

integer

Phân số có dấu của một giây ở độ phân giải nano giây của khoảng thời gian. Thời lượng dưới một giây được biểu thị bằng trường seconds 0 và trường nanos dương hoặc âm. Đối với khoảng thời gian từ một giây trở lên, giá trị khác 0 cho trường nanos phải có cùng dấu với trường seconds. Phải nằm trong khoảng từ -999.999.999 đến +999.999.999 (bao gồm cả hai giá trị này).

Chú thích về công cụ

Chú thích về công cụ được gửi đến ứng dụng MCP để mô tả rủi ro cơ bản của một công cụ nhất định. Hầu hết ứng dụng đều coi những gợi ý này là không đáng tin cậy, nhưng có thể dùng chúng để quyết định thời điểm gửi lời nhắc xác nhận cho người dùng.

Cùng với chuỗi tiêu đề, các gợi ý boolean sau đây được xác định như sau:

  • readOnlyHint: Nếu đúng, công cụ sẽ không sửa đổi môi trường của nó. Mặc định: false.
  • destructiveHint: Nếu đúng, thì công cụ có thể thực hiện các hành động có tính huỷ diệt. Nếu là false, thì công cụ chỉ có thể thực hiện các hành động bổ sung. Mặc định: true.
  • idempotentHint: Nếu đúng, thì việc gọi công cụ nhiều lần với cùng một đối số sẽ không có thêm hiệu ứng nào đối với môi trường của công cụ đó. Mặc định: false.
  • openWorldHint: Nếu đúng, thì công cụ này có thể tương tác với "thế giới mở" của các thực thể bên ngoài. Nếu là false, thì công cụ chỉ có thể tương tác với các thực thể nội bộ. Ví dụ: công cụ tìm kiếm trên web sẽ là công cụ thế giới mở, còn công cụ ghi nhớ sẽ không phải là công cụ thế giới mở.

Gợi ý về hành động huỷ diệt: ❌ | Gợi ý về hành động luỹ đẳng: ❌ | Gợi ý về hành động chỉ đọc: ✅ | Gợi ý về hành động trong thế giới mở: ❌