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 theo lô để phân giải tên vị trí và URL trên 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 đã phân giải 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 Maps Grounding Lite:

Trước khi bắt đầu

Để sử dụng Resolution API, bạn cần có một dự án Google Cloud đã bật tính năng thanh toán và 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 của bạn.

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, mỗi dự án.
• ResolveMapsUrls: 600 truy vấn mỗi phút, mỗi dự án.
• Kích thước lô: Tối đa 20 cụm từ tìm kiếm 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 không mất phí (0 USD) theo SKU Places API Tìm kiếm văn bản Nguyên tắc cơ bản (Chỉ ID). Giống như các tính năng khác của Maps Grounding Lite, dự án của bạn phải có 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à đảm bảo thời gian phản hồi nhanh, 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ặt hàng cho 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ể (ví dụ: "Googleplex, Mountain View, CA" hoặc "Tháp Eiffel, Paris").
  • Các cụm từ tìm kiếm chung chung theo danh mục (ví dụ: "nhà hàng ở New York") hoặc tên chuỗi chung chung 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 Google Maps có cấu trúc hợp lệ.
  • 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/...
  • Chúng tôi không hỗ trợ URL chung của Maps dựa trên cụm từ tìm kiếm (ví dụ: https://maps.google.com/?q=restaurant) và URL không trỏ đến một địa điểm riêng biệt.

Lưu đị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 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 để biết lỗi của 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 (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.
2. 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.
3. 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 một chuỗi trong JSON).
   • Giá trị 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ặt hàng không thành công.
4. saveToMapsUrl chỉ bao gồm các mục đã giải quyết thành công: Đường liên kết saveToMapsUrl chỉ bao gồm các mục đã giải quyết. Không bao gồm các mục không thành công.

Đừng giả định 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:

Chỉ thử lại các 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 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ử gửi 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 hai công cụ:

• resolve_names: Phân giải một loạt tên hoặc địa chỉ đị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ủa Maps Grounding Lite, các công cụ này sẽ được cung cấp cùng với các công cụ khác của Maps Grounding Lite. 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 phân giải (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ụ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ề 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ề API Phân giải, hãy sử dụng thành phần trình theo dõi sự cố công khai của 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