MCP Tools Reference: mapstools.googleapis.com

Công cụ: resolve_names

Phân giải một danh sách theo lô gồm các cụm từ tìm kiếm vị trí cụ thể (tên địa danh hoặc địa chỉ chính xác) thành Mã địa điểm chuẩn trên Google Maps.

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

  1. queries (mảng đối tượng – BẮT BUỘC): Danh sách các cụm từ tìm kiếm vị trí cần phân giải. Bạn có thể chỉ định tối đa 20 cụm từ tìm kiếm.

    • Mỗi đối tượng truy vấn phải có:
      • text (chuỗi – BẮT BUỘC): Cụm từ tìm kiếm dạng văn bản đại diện cho một tên hoặc địa chỉ địa điểm cụ thể cần phân giải.
        • Ví dụ: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (đối tượng – KHÔNG BẮT BUỘC): Sử dụng đối tượng này để ưu tiên kết quả gần một khu vực địa lý cụ thể.

    • Định dạng: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (chuỗi – KHÔNG BẮT BUỘC): Mã vùng CLDR Unicode (mã quốc gia gồm hai chữ cái, ví dụ: US, CA) của người dùng để thiên vị kết quả.

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

  • Tính cụ thể (QUAN TRỌNG): Cụm từ tìm kiếm phải thể hiện tên hoặc địa chỉ của một địa điểm cụ thể. Chúng tôi không hỗ trợ các cụm từ tìm kiếm chung như 'restaurants' hoặc tên chuỗi như 'Starbucks'.
  • KHÔNG gọi công cụ này nếu các công cụ hạ nguồn mà bạn dự định gọi đã chấp nhận trực tiếp chuỗi địa chỉ thô hoặc tên địa điểm.

Lưu vào Google Maps:

  • Phản hồi bao gồm một trường save_to_maps_url: một đường liên kết duy nhất đến Google Maps chứa tất cả địa điểm đã được phân giải thành công.
  • Khi người dùng muốn lưu, chia sẻ hoặc mở các địa điểm đã phân giải dưới dạng danh sách trong Google Maps, hãy hiển thị đường liên kết này cho người dùng. ĐỪNG tự tạo đường liên kết này.

Xử lý lỗi (QUAN TRỌNG):

  • Đây là công cụ xử lý hàng loạt. Một yêu cầu có thể trả về "kết quả hỗn hợp" (ví dụ: một số truy vấn phân giải thành công trong khi một số khác không thành công).
  • Danh sách đầu ra của results được đảm bảo ánh xạ 1:1 với các chỉ mục queries đầu vào. Một truy vấn không thành công sẽ dẫn đến thông báo Result trống (không có entity nào được đặt) tại chỉ mục tương ứng trong danh sách results.
  • Bạn PHẢI kiểm tra trường bản đồ failed_requests trong phản hồi để xác định chỉ mục truy vấn cụ thể nào không thành công. Khoá của failed_requests đại diện cho chỉ mục dựa trên 0 của truy vấn không thành công trong yêu cầu. Đừng cho rằng toàn bộ lệnh gọi theo lô đều không thành công vì một phần không thành công.

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

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": "resolve_names",
    "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 ResolveNames.

ResolveNamesRequest

Biểu diễn dưới dạng JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Trường
queries[]

object (LocationQuery)

Bắt buộc. Danh sách các truy vấn vị trí cần được giải quyết. Bạn có thể chỉ định tối đa 20 cụm từ tìm kiếm.
locationBias

object (LocationBias)

Không bắt buộc. Một khu vực không bắt buộc để ưu tiên kết quả phân giải. Nếu được chỉ định, kết quả phân giải sẽ thiên về các thực thể gần khu vực này hơn. Việc thêm location_bias hoặc region_code thường mang lại kết quả chính xác hơn bằng cách thu hẹp phạm vi tìm kiếm.

Nếu bạn chỉ định cả location_bias và region_code, thì location_bias sẽ được ưu tiên hơn region_code.
regionCode

string

Không bắt buộc. Mã vùng không bắt buộc để ưu tiên kết quả phân giải. Nếu được chỉ định, kết quả phân giải sẽ thiên về các thực thể nằm trong hoặc gần khu vực được chỉ định. Đây phải là mã vùng CLDR. Ví dụ: "US" hoặc "CA". Việc thêm location_bias hoặc region_code thường mang lại kết quả chính xác hơn bằng cách thu hẹp phạm vi tìm kiếm.

Nếu bạn chỉ định cả location_bias và region_code, thì location_bias sẽ được ưu tiên hơn region_code.

LocationQuery

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

string

Bắt buộc. Cụm từ tìm kiếm dạng văn bản để phân giải thành một thực thể không gian địa lý cụ thể trên Google Maps, chẳng hạn như một địa điểm hoặc địa chỉ. Câu hỏi càng cụ thể thì giải pháp càng chính xác. Ví dụ: "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" hoặc "Tháp Eiffel, Paris". Cụm từ tìm kiếm phải là một địa chỉ hoặc tên địa điểm cụ thể. Chúng tôi không hỗ trợ các vị trí khái quát như tên chuỗi cửa hàng (ví dụ: Starbucks) hoặc cụm từ tìm kiếm như "nhà hàng".

LocationBias

Biểu diễn dưới dạng JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Trường
Trường nhóm type. Loại thiên vị vị trí. type chỉ có thể là một trong những trạng thái sau:
viewport

object (Viewport)

Khung nhìn được xác định bằng hộp giới hạn.

Khung nhìn

Biểu diễn dưới dạng JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Trường
low

object (LatLng)

Bắt buộc. Điểm thấp của khung nhìn.
high

object (LatLng)

Bắt buộc. Điểm cao của khung nhìn.

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

Giản đồ đầu ra

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

ResolveNamesResponse

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

object (Result)

Chỉ có đầu ra. Danh sách các thực thể được phân giải từ truy vấn vị trí. Đảm bảo ánh xạ 1:1 với các chỉ mục queries của yêu cầu. Chuỗi trống tại chỉ mục i cho biết không phân giải được cho truy vấn đó. Nếu quá trình phân giải không thành công, vui lòng kiểm tra trường failed_requests để biết trạng thái lỗi.
failedRequests

map (key: integer, value: object (Status))

Chỉ có đầu ra. Một bản đồ thông báo lỗi một phần. Khoá là chỉ mục của yêu cầu không thành công trong trường queries. Giá trị là trạng thái lỗi nêu chi tiết lý do khiến quá trình phân giải không thành công.

Một đối tượng chứa danh sách các cặp "key": value. Ví dụ: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Chỉ có đầu ra. Một đường liên kết để lưu tất cả các thực thể đã được phân giải thành công trong Google Maps.

Kết quả

Biểu diễn dưới dạng JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Trường
entity

object (Entity)

Chỉ có đầu ra. Thực thể được phân giải từ truy vấn vị trí.
confidence

enum (Confidence)

Chỉ có đầu ra. Mức độ tin cậy cho độ phân giải.

Thực thể

Biểu diễn dưới dạng JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Trường
Trường nhóm entity. Loại thực thể đã phân giải. entity chỉ có thể là một trong những trạng thái sau:
place

string

Tên tài nguyên của địa điểm đã phân giải.

FailedRequestsEntry

Biểu diễn dưới dạng JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Trường
key

integer
value

object (Status)

Trạng thái

Biểu diễn dưới dạng JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Trường
code

integer

Mã trạng thái, phải là giá trị enum của google.rpc.Code.
message

string

Thông báo lỗi dành cho nhà phát triển, phải bằng tiếng Anh. Mọi thông báo lỗi mà người dùng thấy đều phải được bản địa hoá và gửi trong trường google.rpc.Status.details hoặc được ứng dụng khách bản địa hoá.
details[]

object

Danh sách các thông báo chứa thông tin cụ thể về lỗi. Có một nhóm gồm nhiều loại thông báo chung để API sử dụng.

Một đối tượng chứa các trường thuộc một loại tuỳ ý. Một trường bổ sung "@type" chứa một URI xác định loại. Ví dụ: { "id": 1234, "@type": "types.example.com/standard/id" }.

Bất kỳ

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

string

Xác định loại thông báo Protobuf được chuyển đổi tuần tự bằng một tham chiếu URI bao gồm một tiền tố kết thúc bằng dấu gạch chéo và tên loại đủ điều kiện.

Ví dụ: type.googleapis.com/google.protobuf.StringValue

Chuỗi này phải chứa ít nhất một ký tự / và nội dung sau ký tự / cuối cùng phải là tên đủ điều kiện của loại ở dạng chuẩn, không có dấu chấm ở đầu. Đừng viết lược đồ trên các tham chiếu URI này để ứng dụng không cố gắng liên hệ với chúng.

Tiền tố là tuỳ ý và các phương thức triển khai Protobuf dự kiến sẽ chỉ cần loại bỏ mọi thứ cho đến và bao gồm cả / cuối cùng để xác định loại. type.googleapis.com/ là tiền tố mặc định phổ biến mà một số cách triển khai cũ yêu cầu. Tiền tố này không cho biết nguồn gốc của loại và các URI chứa tiền tố này không được dự kiến sẽ phản hồi bất kỳ yêu cầu nào.

Tất cả chuỗi URL loại phải là tham chiếu URI hợp lệ với quy định hạn chế bổ sung (đối với định dạng văn bản) rằng nội dung của tham chiếu chỉ được bao gồm các ký tự chữ và số, ký tự thoát được mã hoá theo phần trăm và các ký tự trong tập hợp sau (không bao gồm dấu phẩy ngược bên ngoài): /-.~_!$&()*+,;=. Mặc dù chúng tôi cho phép mã hoá phần trăm, nhưng các phương thức triển khai không được bỏ ký tự thoát để tránh nhầm lẫn với các trình phân tích cú pháp hiện có. Ví dụ: type.googleapis.com%2FFoo sẽ bị từ chối.

Trong thiết kế ban đầu của Any, khả năng khởi chạy dịch vụ phân giải loại tại các URL loại này đã được xem xét, nhưng Protobuf chưa bao giờ triển khai dịch vụ này và coi việc liên hệ với các URL này là có vấn đề và có thể gây ra vấn đề bảo mật. Đừng cố gắng liên hệ với các URL loại.
value

string (bytes format)

Chứa một chuyển đổi tuần tự Protobuf của loại được mô tả bằng type_url.

Một chuỗi được mã hoá base64.

Độ tin cậy

Mức độ tin cậy cho độ phân giải.

Enum
CONFIDENCE_UNSPECIFIED Giá trị mặc định. Giá trị này không được sử dụng.
MEDIUM Mức độ tin cậy trung bình cho biết độ phân giải có thể chính xác nhưng có thể có các ứng cử viên khác.
HIGH Độ tin cậy cao cho biết kết quả phân giải là chính xác và đại diện cho một thực thể không gian địa lý cụ thể (ví dụ: một địa điểm cụ thể).

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