Maps Tools Resolution API (thử nghiệm)

Maps Tools Resolution API cung cấp các điểm cuối xử lý hàng loạt để phân giải tên và URL của vị trí thành mã địa điểm trên Google Maps.

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

Thử nghiệm: Các API ResolveNames và ResolveMapsUrls đang ở giai đoạn Thử nghiệm (giai đoạn trước khi phát hành rộng rãi). Các sản phẩm và tính năng ở giai đoạn trước khi phát hành rộng rãi có thể bị hạn chế về khả năng hỗ trợ, đồng thời những thay đổi đối với các sản phẩm và tính năng ở giai đoạn trước khi phát hành rộng rãi có thể không tương thích với các phiên bản khác ở giai đoạn trước khi phát hành rộng rãi. Các Sản phẩm/dịch vụ ở giai đoạn trước khi phát hành rộng rãi được điều chỉnh theo Điều khoản dành riêng cho dịch vụ của Nền tảng Google Maps. Để biết thêm thông tin, hãy xem phần mô tả về giai đoạn ra mắt. Bạn không phải trả phí khi sử dụng ResolveNames và ResolveMapsUrls trong thời gian các hàm này ở trạng thái Thử nghiệm.

Phương thức xác thực

Các API này hỗ trợ cả thông tin xác thực Khoá API và OAuth 2.0:

1. Khoá API

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

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. Phạm vi OAuth 2.0

Nếu sử dụng uỷ quyền OAuth, bạn có thể dùng các phạm vi sau:

• https://www.googleapis.com/auth/maps-platform.mapstools (Được đề nghị)

Xác thực và ràng buộc 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, 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 API đề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 truy vấn phải chỉ định một tham số văn bản không có nội dung.
  • Cụm từ tìm kiếm phải thể hiện một tên địa điểm hoặc địa chỉ cụ thể (ví dụ: "Googleplex, Mountain View, California", "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 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 về ResolveMapsUrls:
  • Mỗi URL phải là một URL Google Maps hợp lệ về cấu trúc.
  • Các định dạng được hỗ trợ bao gồm:
    • URL tiêu chuẩn của địa điểm: https://www.google.com/maps/place/...
    • URL rút gọn: https://maps.app.goo.gl/...
  • URL Maps dựa trên cụm từ tìm kiếm chung (ví dụ: https://maps.google.com/?q=restaurant) và URL không trỏ đến một địa điểm duy nhất không được hỗ trợ.

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

Cả hai API này đều được thiết kế dưới dạng bộ 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ể không gặp lỗi với lỗi cấp cao nhất. Thay vào đó, API sẽ trả về một phản hồi Thành công một phần.

Cách diễn giải câu trả lời

1. Đảm bảo liên kết 1:1: Danh sách kết quả trả về (đối với ResolveNames) hoặc thực thể (đối với ResolveMapsUrls) sẽ liên kết 1:1 với danh sách đầu vào.
2. Các phần tử trống cho lỗi: Nếu một 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.
   • key 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).
   • value là một đối tượng google.rpc.Status chứa mã lỗi cụ thể (từ các trạng thái gRPC/HTTP tiêu chuẩn) và một thông báo chi tiết giải thích lý do khiến yêu cầu không thành công.

Lỗi cấp cao nhất

Lỗi HTTP cấp cao nhất (ví dụ: 400 Bad Request) chỉ được trả về nếu yêu cầu không xác thực được (ví dụ: khi truyền hơn 20 mục hoặc thiếu các trường bắt buộc).

Quy cách API và ví dụ về Curl

1. ResolveNames API

Phương thức: POST

https://mapstools.googleapis.com/v1alpha: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 giải quyết (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", "FR") để thiên vị kết quả.

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

Cụm từ tìm kiếm này sẽ 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/v1alpha:resolveNames?key=KEY"

Phản hồi JSON

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Ví dụ về 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 rác 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/v1alpha:resolveNames?key=KEY"

Phản hồi JSON

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

Phương thức: POST

https://mapstools.googleapis.com/v1alpha: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 trên Google Maps cần phân giải (Tối đa 20).

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

Phân giải đường liên kết đến một địa điểm tiêu 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

Phản hồi JSON

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Ví dụ về lệnh Curl: Kết quả hỗn hợp (Thất bại một phần)

Phân giải một URL hợp lệ của địa điểm và một URL không hợp lệ/không được hỗ trợ.

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

Phản hồi JSON

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Ví dụ về lệnh Curl: Xác thực không thành công

Cố gắng 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/v1alpha:resolveMapsUrls?key=KEY"

Phản hồi JSON

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