MCP Tools Reference: mapstools.googleapis.com

Công cụ: compute_routes

Tính toán tuyến đường di chuyển giữa điểm xuất phát và điểm đến, có thể thông qua các điểm dừng trung gian. Trả về khoảng cách và thời gian cho mỗi tuyến đường.

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

  1. origin và destination (đối tượng – BẮT BUỘC): Mỗi đối tượng phải được cung cấp bằng cách sử dụng chính xác một trong các đối tượng sau:

    • address (chuỗi, ví dụ: 'Eiffel Tower, Paris'). Các địa điểm, địa danh và doanh nghiệp có tên được phân giải trực tiếp, vì vậy, KHÔNG gọi search_places trước chỉ để mã hoá địa lý một điểm tham chiếu. Thêm mọi thành phố, khu vực hoặc quốc gia mà người dùng đề cập.
    • lat_lng (đối tượng, {"latitude": number, "longitude": number}).
    • place_id (chuỗi, ví dụ: 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'), chẳng hạn như từ search_places.

  2. intermediate_waypoints (mảng đối tượng – KHÔNG BẮT BUỘC): Tối đa 10 điểm dừng để đi qua, theo thứ tự, giữa điểm xuất phát và điểm đến. Định dạng tương tự như origin. Không được hỗ trợ với TRANSIT. Chỉ bao gồm những điểm dừng mà người dùng yêu cầu.

  3. travel_mode (enum – KHÔNG BẮT BUỘC): DRIVE (mặc định), WALK, BICYCLE hoặc TRANSIT.

  4. Thời gian (KHÔNG BẮT BUỘC – đặt tối đa MỘT): Dấu thời gian RFC 3339 có độ lệch UTC, ví dụ: '2026-09-19T08:00:00-07:00'. Mặc định là khởi hành ngay. Đối với TRANSIT, thời gian có thể là tối đa 7 ngày trước hoặc tối đa 100 ngày sau. Đối với các chế độ khác, thời gian có thể lên đến 365 ngày trong tương lai và không được là thời gian trong quá khứ.

    • departure_time: Sử dụng khi người dùng cho biết thời điểm họ sẽ rời đi (ví dụ: "8 giờ sáng mai").
    • arrival_time: Sử dụng khi người dùng cho biết thời điểm họ phải đến (ví dụ: "đến đó trước 9 giờ sáng").

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

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE (mặc định): bỏ qua tình hình giao thông trực tiếp, sự cố và đường bị đóng. Độ trễ thấp nhất.
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL: sử dụng tình trạng giao thông theo thời gian thực (nếu có). Không hỗ trợ WALK hoặc BICYCLE. CHỈ đặt trạng thái 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 đến dự kiến đã điều chỉnh theo tình hình giao thông. Điều này làm tăng chi phí và độ trễ.

  6. location_bias (đối tượng – KHÔNG BẮT BUỘC): {"latitude": number, "longitude": number} dùng để phân biệt tên địa điểm trong địa chỉ điểm trung gian. Nếu tên không rõ ràng (ví dụ: "Springfield") và người dùng không cung cấp khu vực, hãy giữ nguyên tên được cung cấp trong address và đặt location_bias theo khu vực dự kiến thay vì đoán khu vực.

  7. compute_alternative_routes (boolean – KHÔNG BẮT BUỘC): Chỉ đặt thành true khi người dùng yêu cầu các lựa chọn hoặc tuyến đường thay thế. Giá trị mặc định là false, chỉ trả về tuyến đường được đề xuất.

  8. include_polyline (boolean – KHÔNG BẮT BUỘC): Chỉ đặt thành true khi cần có hình học tuyến đường (encoded_polyline). Giá trị mặc định là false.

Hướng dẫn gọi công cụ:

  • Nếu thiếu điểm xuất phát hoặc điểm đến, bạn PHẢI yêu cầu người dùng làm rõ trước khi gọi công cụ.
  • Đối với câu hỏi "A cách B bao xa?", hãy dùng B làm origin và A làm destination.

Ví dụ về lệnh gọi công cụ: {"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"}

Hướng dẫn trả lời:

  • Khi bạn yêu cầu tuyến đường thay thế, các tuyến đường sẽ được sắp xếp theo thứ tự từ nên dùng nhất đến ít nên dùng nhất.
  • Nếu routes trống, hãy thông báo cho người dùng rằng không tìm thấy tuyến đường nào. Đừng đoán tuyến đường.
  • Chỉ nêu những thông tin thực tế do công cụ trả về. KHÔNG tự tạo hướng dẫn từng chặng, tuyến phương tiện công cộng, nhà ga, sân ga hoặc điểm trung chuyển.
  • Kết quả có căn cứ phải được ghi nhận cho nguồn bằng cách sử dụng trường attribution của mỗi tuyến đường (nếu có).

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

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

Giản đồ đầu vào

ComputeRoutesRequest.

ComputeRoutesRequest

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

object (Waypoint)

Bắt buộc. Điểm tham chiếu gốc.
destination

object (Waypoint)

Bắt buộc. Điểm tham chiếu của điểm đến.
travelMode

enum (RouteTravelMode)

Không bắt buộc. Chỉ định phương thức di chuyển.
intermediateWaypoints[]

object (Waypoint)

Không bắt buộc. Các điểm dừng trung gian giữa điểm xuất phát và điểm đến cần đi qua theo thứ tự. Hỗ trợ tối đa 10 điểm tham chiếu trung gian. Không hỗ trợ điểm tham chiếu trung gian khi travel_mode là TRANSIT.
routingPreference

enum (RoutingPreference)

Không bắt buộc. Xác định cách sử dụng dữ liệu lưu lượng truy cập để tính toán tuyến đường. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL không được hỗ trợ khi travel_mode là WALK hoặc BICYCLE. Đối với TRANSIT, thuộc tính này cho phép 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 chậm trễ và huỷ chuyến.
locationBias

object (LatLng)

Không bắt buộc. Một vị trí để ưu tiên kết quả tìm kiếm, chẳng hạn như để phân biệt các cụm từ tìm kiếm dạng văn bản về điểm tham chiếu.
includePolyline

boolean

Không bắt buộc. Có đưa hình nhiều đường được mã hoá vào tuyến đường phản hồi hay không. Giá trị mặc định là false. Khi được đặt thành true, Route.encoded_polyline sẽ được trả về.
computeAlternativeRoutes

boolean

Không bắt buộc. Có tính toán các tuyến đường thay thế ngoài tuyến đường được đề xuất hay không. Giá trị mặc định là false, trong trường hợp đó, chỉ tuyến đường được đề xuất mới được trả về. Khi được đặt thành true, hệ thống sẽ trả về tối đa tất cả các tuyến đường có sẵn, mặc dù có thể không có tuyến đường thay thế cho mọi yêu cầu.
Trường nhóm timing. Chỉ định thời điểm khởi hành từ điểm xuất phát hoặc đến điểm tham chiếu cuối cùng. Mặc định là khởi hành vào thời điểm hiện tại nếu không được chỉ định. Đối với TRANSIT, thời gian phải cách hiện tại tối đa 7 ngày về trước và tối đa 100 ngày về sau. Đối với các phương thức di chuyển khác, thời gian không được là thời gian trong quá khứ và tối đa là 365 ngày trong tương lai. timing chỉ có thể là một trong những trạng thái sau:
departureTime

string (Timestamp format)

Không bắt buộc. Cho biết rằng tuyến đường phải được tính toán dựa trên thời gian khởi hành.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
arrivalTime

string (Timestamp format)

Không bắt buộc. Cho biết tuyến đường phải được tính toán dựa trên thời gian đến.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

Dấu thời gian

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

string (int64 format)

Biểu thị số giây theo giờ UTC kể từ thời gian Unix 1970-01-01T00:00:00Z. Phải nằm trong khoảng từ -62135596800 đến 253402300799 (tương ứng với 0001-01-01T00:00:00Z đến 9999-12-31T23:59:59Z).
nanos

integer

Phân số không âm của một giây ở độ phân giải nano giây. Trường này là phần nano giây của thời lượng, chứ không phải là giá trị thay thế cho giây. Giá trị giây âm có phân số vẫn phải có giá trị nano không âm, được tính theo thời gian. Phải nằm trong khoảng từ 0 đến 999.999.999.

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 để biểu thị 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].

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 Ý: Tuyến đường 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.

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ề tuyến đường. 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ư thông tin về 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ễ. Tính năng này chỉ dành cho những khách hàng có trong danh sách cho phép. Nếu không có trong danh sách cho phép, yêu cầu sẽ quay lại ROUTING_PREFERENCE_TRAFFIC_UNAWARE.

Giản đồ đầu ra

ComputeRoutesResponse.

ComputeRoutesResponse

Biểu diễn dưới dạng JSON 
{
  "routes": [
    {
      object (Route)
    }
  ]
}
Trường
routes[]

object (Route)

Chứa các tuyến đường giữa điểm xuất phát và điểm đến được yêu cầu, được sắp xếp từ tuyến đường nên dùng nhất đến tuyến đường ít nên dùng nhất. Chỉ một tuyến đường được trả về, trừ phi ComputeRoutesRequest.compute_alternative_routes được đặt thành true.

Tuyến đường

Biểu diễn dưới dạng JSON 
{
  "distanceMeters": integer,
  "duration": string,
  "attribution": {
    object (Attribution)
  },
  "encodedPolyline": string,
  "retrievalToken": string
}
Trường
distanceMeters

integer

Quãng đường di chuyển của tuyến đường, tính bằng mét.
duration

string (Duration format)

Thời gian cần thiết để đi theo tuyến đường.

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".
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 tuyến đường.
encodedPolyline

string

Hình nhiều đường được mã hoá của tuyến đường. Xem https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

Mã thông báo có thể dùng để truy xuất tuyến đường cụ thể này trong các công cụ hạ nguồn, chẳng hạn như SearchAlongRoute. Có hiệu lực trong 10 phút.

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 có giá trị 0 và trường nanos có giá trị 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.

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ả.

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ụ 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ở: ❌