Maps Tools Resolution API

Maps Tools Resolution API là một phần của Maps Grounding Lite. API này cung cấp các điểm cuối hàng loạt giúp 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 có một đường liên kết giúp lưu các địa điểm đã phân giải dưới dạng một danh sách trong Google Maps.

Resolution API có sẵn dưới dạng cả phương thức REST và công cụ trên máy chủ MCP Maps Grounding Lite:

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à bật dịch vụ API Maps Grounding Lite. Để biết hướng dẫn, hãy xem phần Bật dịch vụ Maps Grounding Lite trên dự á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 đăng nhập 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 hợp lệ của Google Maps Platform 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 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, trên mỗi dự án.
• ResolveMapsUrls: 600 truy vấn mỗi phút, trên mỗi dự án.
• Kích thước lô: Tối đa 20 truy vấn hoặc URL cho 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 sẽ không bị tính phí ($0) theo SKU Places API Text Search Essentials (Chỉ mã nhận dạng). Giống như các phần còn lại của Maps Grounding Lite, dự án của bạn phải có một tài khoản thanh toán.

Xác thực và các ràng buộc đối với yêu cầu

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

• 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 cho mỗi yêu cầu.
• Yêu cầu ResolveNames:
  • Mỗi mục trong queries phải chỉ định một tham số text không có nội dung.
  • Cụm từ tìm kiếm phải đại diện cho một tên địa điểm hoặc địa chỉ cụ thể (ví dụ: "Googleplex, Mountain View, California" hoặc "Tháp Eiffel, Paris").
  • Các cụm từ tìm kiếm chung theo danh mục (ví dụ: "nhà hàng ở New York") hoặc tên chuỗi cửa hàng chung chung mà không có vị trí (ví dụ: "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 hợp lệ về cấu trúc của Google Maps.
  • Các định dạng được hỗ trợ bao gồm:
    • URL chuẩn của địa điểm: https://www.google.com/maps/place/...
    • URL rút gọn: https://maps.app.goo.gl/...
  • URL chung dựa trên cụm từ tìm kiếm trên Maps (ví dụ: https://maps.google.com/?q=restaurant) và URL không trỏ đến một địa điểm duy nhất sẽ không được hỗ trợ.

Lưu các địa điểm đã phân giải 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 đến Google Maps duy nhất chứa tất cả những đị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 có 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 này sẽ trả về một phản hồi thành công một phần và bạn phải kiểm tra phản hồi để biết các lỗi theo từng mục.

Diễn giải câu trả lời

1. Đảm bảo căn chỉnh 1:1: Danh sách results được trả về (cho ResolveNames) hoặc danh sách entities (cho ResolveMapsUrls) ánh xạ 1:1 với danh sách đầu vào, theo chỉ mục.
2. Cá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, danh sách kết quả sẽ chứa một đối tượng trống {} tại chỉ mục i.
3. failedRequests map: 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 một 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 này không thành công.
4. saveToMapsUrl chỉ bao gồm các trường hợp thành công: Đường liên kết saveToMapsUrl chỉ bao gồm những mục đã được giải quyết. Các mục không thành công sẽ không được đưa vào.

Đừng giả định rằng toàn bộ lô đã thất bại vì một mục thất bại. Luôn kiểm tra failedRequests để biết những mặt hàng nào (nếu có) không thể giải quyết.

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

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

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 này sẽ 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 nhiều 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ụ: khoá API bị thiếu hoặc không hợp lệ, hoặc yêu cầu vượt quá giới hạn sử dụng.
• Lỗi máy chủ (500 INTERNAL): Thử lại yêu cầu.

Sử dụng Resolution API với MCP

Máy chủ MCP Maps Grounding Lite tại https://mapstools.googleapis.com/mcp hiển thị Resolution API dưới dạng 2 công cụ:

• resolve_names: Giải quyết một loạt tên hoặc địa chỉ vị trí thành mã địa điểm.
• resolve_maps_urls: Phân giải một nhóm 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 Maps Grounding Lite, những công cụ này sẽ có sẵn cùng với các công cụ Maps Grounding Lite khác. 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 ràng buộc và trả về cùng một phản hồi thất bại một phần như các phương thức REST.

Phản hồi của công cụ bao gồm trường save_to_maps_url. Phần 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 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 các truy vấn lặp lại cần phân giải (tối đa 20).
• locationBias (Không bắt buộc): Khung giới hạn khung nhìn để điều chỉnh kết quả theo 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: Phân giải thành công

Cụm từ tìm kiếm 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ề lệnh curl: Kết quả hỗn hợp (lỗi một phần)

Trong ví dụ này, mục đầu tiên là văn bản không phân giải được 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 gồm các chuỗi URL của Google Maps cần phân giải (tối đa 20).

Ví dụ về curl: Phân giải thành công

Ví dụ sau đây phân giải một URL tiêu chuẩn của địa điểm 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ề lệnh curl: Kết quả hỗn hợp (lỗi một phần)

Ví dụ sau đây phân giải một URL hợp lệ của địa điểm 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: Xác thực không thành công

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

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 lỗi công khai Maps Grounding Lite:

• Báo cáo lỗi
• Gửi yêu cầu về tính năng
• Gửi phản hồi