MCP Tools Reference: mapstools.googleapis.com

Công cụ: search_places

Gọi công cụ này khi người dùng yêu cầu tìm địa điểm, doanh nghiệp, địa chỉ, vị trí, địa điểm yêu thích hoặc bất kỳ nội dung tìm kiếm có liên quan nào khác liên quan đến Google Maps.

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

  1. text_query (chuỗi – BẮT BUỘC): Cụm từ tìm kiếm chính. Điều này phải xác định rõ ràng những gì người dùng đang tìm kiếm.

    • Ví dụ: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
    • Đối với thông tin chi tiết về địa điểm cụ thể: Thêm thuộc tính được yêu cầu (ví dụ: 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

  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: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • Cách sử dụng:
      • Để thiên về bán kính 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Để thiên về điểm giữa: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (bỏ qua radius_meters).

  3. language_code (chuỗi – KHÔNG BẮT BUỘC): Ngôn ngữ dùng để hiển thị bản tóm tắt kết quả tìm kiếm.

    • Định dạng: Mã ngôn ngữ gồm hai chữ cái (ISO 639-1), có thể theo sau là dấu gạch dưới và mã quốc gia gồm hai chữ cái (ISO 3166-1 alpha-2), ví dụ: en, ja, en_US, zh_CN, es_MX. Nếu bạn không cung cấp mã ngôn ngữ, kết quả sẽ được trả về bằng tiếng Anh.

  4. region_code (chuỗi – KHÔNG BẮT BUỘC): Mã vùng CLDR Unicode của người dùng. Tham số này được dùng để hiển thị Place Details, chẳng hạn như tên địa điểm theo khu vực cụ thể (nếu có). Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

    • Định dạng: Mã quốc gia gồm hai chữ cái (ISO 3166-1 alpha-2), ví dụ: US, CA.

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

  • Thông tin vị trí (QUAN TRỌNG): Nội dung tìm kiếm phải chứa đủ thông tin vị trí. Nếu vị trí không rõ ràng (ví dụ: chỉ "quán pizza"), bạn phải chỉ định vị trí đó trong text_query (ví dụ: "quán pizza ở New York") hoặc sử dụng tham số location_bias. Thêm tên thành phố, tiểu bang/tỉnh và khu vực/quốc gia nếu cần để phân biệt.

  • Luôn cung cấp text_query cụ thể và có nhiều ngữ cảnh nhất có thể.

  • Chỉ sử dụng location_bias nếu toạ độ được cung cấp rõ ràng hoặc nếu việc suy luận vị trí từ bối cảnh đã biết của người dùng là phù hợp và cần thiết để có kết quả tốt hơn.

  • Kết quả có căn cứ phải được ghi nhận cho nguồn bằng cách sử dụng thông tin trong trường attribution (nếu có).

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

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_places",
    "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 SearchText.

SearchTextRequest

Biểu diễn dưới dạng JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "includeExtendedDetails": boolean,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}
Trường
textQuery

string

Bắt buộc. Cụm từ tìm kiếm dạng văn bản.
languageCode

string

Không bắt buộc. Ngôn ngữ mà bạn muốn nhận bản tóm tắt. Nếu mã ngôn ngữ không được chỉ định hoặc không được nhận dạng, thì bản tóm tắt ưu tiên tiếng Anh sẽ được trả về.

Ví dụ: "en" cho tiếng Anh.

Danh sách ngôn ngữ hiện được hỗ trợ: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

Không bắt buộc. Mã quốc gia/khu vực Unicode (CLDR) của vị trí nơi yêu cầu được gửi đến. Tham số này được dùng để hiển thị Place Details, chẳng hạn như tên địa điểm theo khu vực cụ thể (nếu có). Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

Ví dụ: "US" cho Hoa Kỳ.

Để biết thêm thông tin, hãy xem https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.

Xin lưu ý rằng mã vùng gồm 3 chữ số hiện chưa được hỗ trợ.
pageSize

integer

Không bắt buộc. Số lượng địa điểm tối đa cần trả về, tối đa là 5. Dịch vụ có thể trả về ít hơn giá trị này. Giá trị mặc định là 5.
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 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 chuyên biệt của cơ sở, chính sách/mẹo dành cho khách, thời gian chờ.

Để trống false (mặc định) cho các cụm từ tìm kiếm khám phá thông thường (ví dụ: ẩm thực, loại cửa hàng), thông tin 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 thông thường.

Việc bật trường này sẽ làm tăng độ trễ.

Trường nhóm _location_bias.

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

object (LocationBias)

Một khu vực không bắt buộc để ưu tiên kết quả tìm kiếm. Nếu một vị trí rõ ràng nằm trong text_query, thì vị trí đó sẽ được dùng để thiên vị kết quả tìm kiếm thay vì trường này.

LocationBias

Biểu diễn dưới dạng JSON 
{
  "circle": {
    object (Circle)
  }
}
Trường
circle

object (Circle)

Không bắt buộc. Một hình tròn được xác định bằng tâm và bán kính. radius_meters là không bắt buộc. Nếu bạn không đặt, kết quả sẽ thiên về điểm trung tâm.

Hình tròn

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

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}
Trường
center

object (LatLng)

Bắt buộc. Tâm của hình tròn.

Trường nhóm _radius_meters.

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

number

Bán kính của hình tròn tính bằng mét. Bán kính phải trong phạm vi 50.000 mé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].

Giản đồ đầu ra

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

SearchTextResponse

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

object (PlaceView)

Chỉ có đầu ra. Danh sách các địa điểm được đề cập trong bản tóm tắt.
summary

string

Chỉ có đầu ra. Bản tóm tắt bằng ngôn ngữ tự nhiên về kết quả tìm kiếm. Bản tóm tắt có thể chứa các trích dẫn bắt đầu từ 0 như "[0]", "[1]", "[2]", v.v. Các trích dẫn này liên kết đến các địa điểm tương ứng trong trường places.
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ề.

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í điểm đến và sử dụng phương thức di chuyển mặc định DRIVE.
placeUrl

string

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

string

Đườ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ả.

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