Sử dụng thêm các tính năng của công cụ tác nhân cho Maps Experiments với SKU Pro! Tìm hiểu về gói Pro

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Maps Tools Resolution API

Maps Tools Resolution API là một phần của các công cụ tác nhân cho trải nghiệm trên Maps (trước đây là Maps Grounding Lite). API này cung cấp các điểm cuối theo lô để phân giải tên vị trí và URL của Google Maps thành mã địa điểm trên Google Maps. Bạn có thể sử dụng mã địa điểm được trả về với các API khác của Google Maps Platform. Mỗi câu trả lời cũng bao gồm một đường liên kết để lưu các địa điểm đã được giải quyết dưới dạng danh sách trong Google Maps.

Resolution API được cung cấp dưới dạng cả phương thức REST và công cụ trên máy chủ MCP của các công cụ tác nhân cho trải nghiệm trên Maps:

Chức năng	Phương thức REST	Công cụ MCP
Phân giải tên hoặc địa chỉ vị trí thành địa điểm	`resolveNames`	`resolve_names`
Phân giải URL trên Google Maps thành địa điểm	`resolveMapsUrls`	`resolve_maps_urls`

Trước khi bắt đầu

Để sử dụng Resolution API, bạn cần có một dự án trên đám mây của Google Cloud đã bật tính năng thanh toán và dịch vụ API Maps Experience agent tools. Để biết hướng dẫn, hãy xem bài viết Bật các công cụ tác nhân cho trải nghiệm Maps Experiments trong dự án trên đám mây của bạn trên Google Cloud.

Quyền truy cập và xác thực API

Resolution API hỗ trợ cả khoá API và thông tin xác thực OAuth 2.0.

Khóa API

Bạn có thể xác thực các yêu cầu bằng cách truyền một khoá API Google Maps Platform hợp lệ trong tiêu đề X-Goog-Api-Key hoặc bằng cách thêm khoá đó vào URL yêu cầu:

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

Trong các ví dụ trên trang này, hãy thay thế API_KEY bằng khoá API của bạn.

Phạm vi OAuth 2.0

Nếu bạn sử dụng quy trình uỷ quyền OAuth, thì phạm vi sau đây sẽ được hỗ trợ:

https://www.googleapis.com/auth/maps-platform.mapstools

Hạn mức sử dụng

Các hạn mức mặc định sau đây áp dụng cho Resolution API:

ResolveNames: 600 truy vấn mỗi phút cho mỗi dự án.
ResolveMapsUrls: 600 truy vấn mỗi phút cho mỗi dự án.
Kích thước lô: Tối đa 20 cụm từ tìm kiếm hoặc URL trong mỗi yêu cầu.

Mỗi yêu cầu được tính là một truy vấn, bất kể yêu cầu đó chứa bao nhiêu mục.

Giá

Các yêu cầu đến ResolveNames và ResolveMapsUrls được tính phí không mất phí (0 USD) theo SKU Places API Tìm kiếm văn bản Essentials (IDs Only). Giống như các công cụ tác nhân khác cho trải nghiệm trên Maps, dự án của bạn phải có một tài khoản thanh toán.

Xác thực yêu cầu và các quy tắc ràng buộc

Để ngăn chặn tình trạng quá tải và giúp đảm bảo thời gian phản hồi nhanh, các yêu cầu theo lô được xác thực theo các quy tắc sau:

Giới hạn kích thước lô: Cả hai phương thức đều cho phép tối đa 20 mục trong mỗi yêu cầu.
Yêu cầu đối với ResolveNames:
- Mỗi mục trong queries phải chỉ định một tham số text không 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 hạn như "Googleplex, Mountain View, CA" hoặc "Eiffel Tower, Paris".
- Các cụm từ tìm kiếm chung chung theo danh mục, chẳng hạn như "restaurants in New York", hoặc tên chuỗi chung chung không có vị trí, chẳng hạn như "Starbucks", không được hỗ trợ và có thể không phân giải được.
Yêu cầu đối với ResolveMapsUrls:
- Mỗi URL phải là một URL Google Maps hợp lệ về mặt cấu trúc.
- Các định dạng được hỗ trợ bao gồm:
  - URL địa điểm chuẩn: https://www.google.com/maps/place/...
  - URL rút gọn: https://maps.app.goo.gl/...
- URL chung của Maps dựa trên cụm từ tìm kiếm, chẳng hạn như https://maps.google.com/?q=restaurant và URL không trỏ đến một địa điểm riêng biệt đều không được hỗ trợ.

Lưu các địa điểm đã giải quyết vào Google Maps

Nếu ít nhất một mục trong một lô được phân giải, thì phản hồi sẽ bao gồm một trường saveToMapsUrl. Đây là một đường liên kết duy nhất đến Google Maps, chứa tất cả các địa điểm đã được phân giải thành công trong lô. Cung cấp đường liên kết này cho những 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.

Luôn sử dụng đường liên kết do API trả về. Đừng tự tạo đường liên kết. Nếu không có mục nào trong lô được phân giải, thì phản hồi sẽ không bao gồm saveToMapsUrl.

Xử lý lỗi một phần

Cả hai phương thức đều là trình xử lý hàng loạt. Nếu một số mục trong một lô không phân giải được, thì yêu cầu tổng thể sẽ không gặp lỗi cấp cao nhất. Thay vào đó, API sẽ trả về phản hồi thành công một phần và bạn phải kiểm tra phản hồi để tìm lỗi theo từng mục.

Diễn giải phản hồi

Đảm bảo căn chỉnh 1:1: Danh sách results (cho ResolveNames) hoặc danh sách entities (cho ResolveMapsUrls) được trả về sẽ liên kết 1:1 với danh sách đầu vào, theo chỉ mục.
Phần tử trống cho lỗi: Nếu mục tại chỉ mục i không phân giải được, thì danh sách kết quả sẽ chứa một đối tượng trống {} tại chỉ mục i.
Bản đồ failedRequests: Phản hồi chứa một bản đồ failedRequests.
- Khoá là chỉ mục dựa trên 0 của mục không thành công (được biểu thị dưới dạng chuỗi trong JSON).
- Giá trị này là một đối tượng google.rpc.Status chứa mã lỗi và thông báo giải thích lý do mục không thành công.
saveToMapsUrl chỉ bao gồm các mục thành công: Đường liên kết saveToMapsUrl chỉ bao gồm các mục đã được giải quyết. Không bao gồm các mục không thành công.

Đừng cho rằng toàn bộ lô đều không thành công vì một mục không thành công. Hãy luôn kiểm tra failedRequests để tìm hiểu xem có mặt hàng nào không thể giải quyết được hay không.

Lỗi theo từng mặt hàng

Bảng sau đây liệt kê các lỗi theo từng mặt hàng mà bạn có thể thấy trong failedRequests:

Phương thức	Nguyên nhân	Mã	Nhắn tin
`ResolveNames`	Không thể phân giải tên hoặc địa chỉ thành một địa điểm.	`5` (`NOT_FOUND`)	`Place not found.`
`ResolveMapsUrls`	Không thể phân giải URL thành một địa điểm.	`3` (`INVALID_ARGUMENT`)	`Failed to resolve Maps URL to a place.`
Cả hai phương thức	Đã xảy ra lỗi nội bộ trong khi giải quyết mục này.	`13` (`INTERNAL`)	`Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support`

Chỉ thử lại những mục không thành công bằng INTERNAL.

Lỗi cấp cao nhất

API trả về lỗi cấp cao nhất thay vì phản hồi một phần trong các trường hợp sau:

Yêu cầu không hợp lệ (400 INVALID_ARGUMENT): Yêu cầu chứa hơn 20 mục, yêu cầu ResolveNames không có cụm từ tìm kiếm hoặc có cụm từ tìm kiếm có giá trị text trống, hoặc yêu cầu ResolveMapsUrls có URL trống hoặc không phải là URL hợp lệ về mặt cú pháp. Một mục không hợp lệ sẽ khiến toàn bộ yêu cầu không thành công.
Lỗi xác thực, quyền hoặc hạn mức: Ví dụ: thiếu khoá API hoặc khoá API không hợp lệ, hoặc yêu cầu vượt quá giới hạn sử dụng.
Lỗi phía máy chủ (500 INTERNAL): Thử lại yêu cầu.

Sử dụng Resolution API với MCP

Máy chủ MCP của các công cụ tác nhân cho trải nghiệm trên Maps tại https://mapstools.googleapis.com/mcp hiển thị Resolution API dưới dạng hai công cụ:

resolve_names: Phân giải một loạt tên hoặc địa chỉ của địa điểm thành mã địa điểm.
resolve_maps_urls: Phân giải một loạt URL trên Google Maps thành mã địa điểm.

Khi bạn định cấu hình LLM để sử dụng máy chủ MCP, các công cụ này sẽ có sẵn cùng với các công cụ tác nhân khác cho Maps Experiments. Các công cụ này chấp nhận cùng một dữ liệu đầu vào, thực thi cùng một quy tắc ràng buộc và trả về cùng một phản hồi lỗi một phần như các phương thức REST.

Câu trả lời của công cụ bao gồm trường save_to_maps_url. Nội dung mô tả công cụ hướng dẫn LLM trình bày đường liên kết này 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, thay vì tự tạo đường liên kết.

Ví dụ sau đây sử dụng curl để gọi trực tiếp công cụ resolve_names:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Để gọi resolve_maps_urls, hãy đặt name thành resolve_maps_urls và truyền một mảng urls trong arguments.

Quy cách của API REST và ví dụ về curl

ResolveNames

Phương thức: POST

https://mapstools.googleapis.com/v1:resolveNames

Định dạng nội dung yêu cầu

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

queries (Bắt buộc): Danh sách lặp lại các truy vấn cần giải quyết (tối đa 20).
locationBias (Không bắt buộc): Hộp giới hạn khung nhìn để ưu tiên kết quả cho một khu vực địa phương.
regionCode (Không bắt buộc): Mã quốc gia CLDR (ví dụ: "US" hoặc "FR") để thiên vị kết quả.

Ví dụ về Curl: Giải quyết thành công

Câu hỏi này phân giải "Googleplex" và "Tháp Eiffel".

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

Nội dung phản hồi JSON

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Ví dụ về Curl: Kết quả hỗn hợp (không thành công một phần)

Trong ví dụ này, mục đầu tiên là văn bản không thể phân giải và mục thứ hai là một địa điểm hợp lệ.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

Nội dung phản hồi JSON

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Phương thức: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

Định dạng nội dung yêu cầu

{
  "urls": [
    "string"
  ]
}

urls (Bắt buộc): Danh sách lặp lại các chuỗi URL của Google Maps cần phân giải (tối đa 20).

Ví dụ về Curl: Giải quyết thành công

Ví dụ sau đây phân giải một URL địa điểm chuẩn trên Google Maps:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

Nội dung phản hồi JSON

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Ví dụ về Curl: Kết quả hỗn hợp (không thành công một phần)

Ví dụ sau đây phân giải một URL địa điểm hợp lệ và một URL không thể phân giải thành địa điểm:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

Nội dung phản hồi JSON

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Ví dụ về Curl: Không xác thực được

Ví dụ sau đây truyền hơn 20 URL trong một yêu cầu:

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

Nội dung phản hồi JSON

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Gửi phản hồi

Để báo cáo vấn đề hoặc chia sẻ ý kiến phản hồi về Resolution API, hãy sử dụng thành phần trình theo dõi sự cố công khai của các công cụ tác nhân cho trải nghiệm trên Maps:

Maps Tools Resolution API Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Trước khi bắt đầu

Quyền truy cập và xác thực API

Khóa API

Phạm vi OAuth 2.0

Hạn mức sử dụng

Giá

Xác thực yêu cầu và các quy tắc ràng buộc

Lưu các địa điểm đã giải quyết vào Google Maps

Xử lý lỗi một phần

Diễn giải phản hồi

Lỗi theo từng mặt hàng

Lỗi cấp cao nhất

Sử dụng Resolution API với MCP

Quy cách của API REST và ví dụ về curl

ResolveNames

Phương thức: POST

Định dạng nội dung yêu cầu

Ví dụ về Curl: Giải quyết thành công

Nội dung phản hồi JSON

Ví dụ về Curl: Kết quả hỗn hợp (không thành công một phần)

Nội dung phản hồi JSON

ResolveMapsUrls

Phương thức: POST

Định dạng nội dung yêu cầu

Ví dụ về Curl: Giải quyết thành công

Nội dung phản hồi JSON

Ví dụ về Curl: Kết quả hỗn hợp (không thành công một phần)

Nội dung phản hồi JSON

Ví dụ về Curl: Không xác thực được

Nội dung phản hồi JSON

Gửi phản hồi

Maps Tools Resolution API