MCP Tools Reference: mapstools.googleapis.com

Công cụ: resolve_names

Phân giải một danh sách hàng loạt các truy vấn vị trí cụ thể (tên địa danh hoặc địa chỉ chính xác) thành mã địa điểm chính tắc của Google Maps.

Yêu cầu về thông tin đầu vào (QUAN TRỌNG):

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

    • 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 bằng văn bản biểu thị một tên địa điểm hoặc địa chỉ 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 tham số 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 2 chữ cái, ví dụ: US, CA) của người dùng để điều chỉnh kết quả.

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

  • Tính cụ thể (RẤT QUAN TRỌNG): Cụm từ tìm kiếm phải thể hiện một tên địa điểm hoặc địa chỉ cụ thể. Chúng tôi không hỗ trợ các cụm từ tìm kiếm chung chung như 'restaurants' hoặc tên chuỗi cửa hàng 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 các chuỗi địa chỉ thô hoặc tên địa điểm.

Xử lý lỗi (CRITICAL):

  • Đây là một 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 những truy vấn khác không phân giải được).
  • 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 biểu thị 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 giả định rằng toàn bộ lệnh gọi hàng loạt đều không thành công do một phần không thành công.

Mẫu sau đây minh hoạ cách sử dụng curl để gọi công cụ resolve_names MCP.

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 tool's MCP 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ề vị trí cần được phân giải. 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 để thiên vị kết quả phân giải. Nếu được chỉ định, kết quả phân giải sẽ thiên về những 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ả tốt hơn bằng cách thu hẹp không gian 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ã khu vực không bắt buộc để thiên vị kết quả phân giải. Nếu được chỉ định, kết quả phân giải sẽ thiên về những thực thể ở 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ả tốt hơn bằng cách thu hẹp không gian 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ụm từ tìm kiếm càng cụ thể thì độ phân giải càng chính xác. Ví dụ: "San Francisco", "Googleplex, Mountain View, California", "1600 Amphitheatre Parkway, Mountain View, California" 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í chung chung như tên chuỗi (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 độ lệch 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 một hộp bao quanh.

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 nhất của khung nhìn.
high

object (LatLng)

Bắt buộc. Điểm cao nhất 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)
    },
    ...
  }
}
Trường
results[]

object (Result)

Chỉ có đầu ra. Danh sách các thực thể được phân giải từ các 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. Một chuỗi trống tại chỉ mục i cho biết quá trình phân giải không thành công 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 đồ cho biết các 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ị này là trạng thái lỗi cho biế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" }.

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 của độ 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 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 một lược đồ trên các tham chiếu URI này để máy khách không cố gắng liên hệ với chúng.

Tiền tố này là tuỳ ý và các triển khai Protobuf 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à một tiền tố mặc định phổ biến mà một số 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 mong đợi phản hồi bất kỳ yêu cầu nào.

Tất cả các chuỗi URL loại đều phải là các tham chiếu URI hợp lệ với hạn chế bổ sung (đối với định dạng văn bản) là nội dung của tham chiếu chỉ được chứa các ký tự chữ và số, các ký tự thoát được mã hoá theo tỷ lệ phần trăm và các ký tự trong tập hợp sau (không bao gồm dấu nhá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 thoát mã hoá để 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 phải bị từ chối.

Trong thiết kế ban đầu của Any, khả năng ra mắt dịch vụ phân giải loại tại các URL loại này đã được cân nhắc nhưng Protobuf chưa bao giờ triển khai dịch vụ nào 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)

Lưu trữ một quy trình 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 của độ phân giải.

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

Chú giải công cụ

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