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 nào khác liên quan đến Google Maps.

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

  1. text_query (chuỗi – BẮT BUỘC): Cụm từ tìm kiếm chính. Bạn phải xác định rõ 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ề một đị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 tham số 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:
      • Để ưu tiên bán kính 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Để thiên về điểm trung tâm: {"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ữ để hiển thị nội dung 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ẽ 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ị thông tin chi tiết về địa điểm, chẳng hạn như tên địa điểm theo khu vực (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 về lệnh gọi công cụ:

  • Thông tin vị trí (QUAN TRỌNG): Cụm từ tìm kiếm phải có đủ thông tin vị trí. Nếu vị trí không rõ ràng (ví dụ: chỉ là "nơi bán pizza"), bạn phải chỉ định vị trí đó trong text_query (ví dụ: "pizza places in 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ể nhất và giàu ngữ cảnh nhất có thể.

  • Chỉ sử dụng location_bias nếu bạn cung cấp toạ độ một cách 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.

Mẫu sau đây minh hoạ cách sử dụng curl để gọi công cụ search_places 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": "search_places",
    "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 SearchText.

SearchTextRequest

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

  // 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 bằ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 các ngôn ngữ được hỗ trợ hiện tại: 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 đưa ra. Tham số này được dùng để hiển thị thông tin chi tiết về địa điểm, chẳng hạn như tên địa điểm theo khu vực (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 không được hỗ trợ.
pageSize

integer

Không bắt buộc. Số lượng địa điểm tối đa cần trả về. Dịch vụ có thể trả về ít hơn giá trị này.
pageToken

string

Không bắt buộc. Mã thông báo trang nhận được từ một lệnh gọi SearchText trước đó. Cung cấp thông tin này để truy xuất trang tiếp theo.

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 để điều chỉnh kết quả tìm kiếm. Nếu có một vị trí rõ ràng trong text_query, thì vị trí đó sẽ được dùng để điều chỉnh 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 điể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 (google.type.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 (google.type.LatLng)

Bắt buộc. Điểm 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 nằm 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,
  "nextPageToken": string
}
Trường
places[]

object (PlaceView)

Chỉ có đầu ra. Danh sách những địa điểm được nhắc đến trong phầ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, chẳng hạn như "[0]", "[1]", "[2]", v.v. Các trích dẫn này liên kết đến các vị trí tương ứng trong trường places.
nextPageToken

string

Không bắt buộc. Một mã thông báo có thể được gửi dưới dạng page_token để truy xuất trang tiếp theo.

PlaceView

Biểu diễn dưới dạng JSON 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (google.type.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 thao tác khác nhau trên Google Maps.

Trường nhóm _location.

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

object (google.type.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 để chỉ đường đến địa điểm. Đường liên kết này chỉ điền sẵn vị trí đích đến và sử dụng chế độ di chuyển mặc định là 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 bài đánh giá về địa điểm này trên Google Maps.

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