Maps Tools Resolution API (thử nghiệm)

API Giải quyết vấn đề về công cụ Maps cung cấp các điểm cuối xử lý hàng loạt để giải quyết tên địa điểm và URL thành Mã địa điểm trên Google Maps.

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

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

Các API 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 Nền tảng Google Maps 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 phương thức uỷ quyền OAuth, thì các phạm vi sau đây được hỗ trợ:

• 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 tải quá mức và đảm bảo thời gian phản hồi nhanh, các yêu cầu hàng loạt được xác thực nghiêm ngặt:

• Giới hạn kích thước hàng loạt: Cả hai API đều cho phép tối đa 20 mục cho mỗi yêu cầu.
• Yêu cầu đối với ResolveNames:
  • Mỗi mục truy vấn phải chỉ định một tham số văn bản không trống.
  • Các truy vấn phải đại diện cho một tên địa điểm hoặc địa chỉ cụ thể (ví dụ: "Googleplex, Mountain View, CA", "Tháp Eiffel, Paris").
  • Các tìm kiếm theo danh mục chung (ví dụ: "nhà hàng ở New York") hoặc tên chuỗi 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 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 tiêu chuẩn: https://www.google.com/maps/place/...
    • URL rút gọn: https://maps.app.goo.gl/...
  • Các URL Maps dựa trên truy vấn chung (ví dụ: https://maps.google.com/?q=restaurant) và các 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 đề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 ở cấp cao nhất. Thay vào đó, API sẽ trả về phản hồi Thành công một phần.

Cách diễn giải phản hồi

1. Đảm bảo căn chỉnh 1:1: Các kết quả được trả về (đối với ResolveNames) hoặc các thực thể (đối với ResolveMapsUrls) sẽ ánh xạ danh sách 1:1 với danh sách đầu vào.
2. Phần tử trống cho các lỗi: Nếu một 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 bản đồ failedRequests.
   • Khoá là chỉ mục dựa trên 0 của mục bị lỗi (được biểu thị dưới dạng chuỗi trong JSON).
   • Giá trị 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 lỗi.

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ề lệnh curl

1. API ResolveNames

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 truy vấn lặp lại để 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", "FR") để ưu tiên kết quả.

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

Truy vấn 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/v1alpha:resolveNames?key=KEY"

Nội dung phản hồi JSON

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

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 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"

Nội dung phản hồi JSON

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

2. API ResolveMapsUrls

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 chuỗi URL Google Maps lặp lại để phân giải (Tối đa 20).

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

Phân giải một đường liên kế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"

Nội dung phản hồi JSON

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

Ví dụ về lệnh curl: Kết quả hỗn hợp (Lỗi một phần)

Phân giải một URL địa điểm hợp lệ và một URL bị lỗi/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"

Nội dung phản hồi JSON

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

Ví dụ về lệnh curl: Lỗi xác thực

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"

Nội dung phản hồi JSON

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