地圖工具解析度 API (實驗性)

地圖工具解析 API 提供批次處理端點，可將地點名稱和網址解析為 Google 地圖地點 ID。

API 存取權和驗證

驗證方法

API 支援 API 金鑰和 OAuth 2.0 憑證：

1. API 金鑰

如要驗證要求，請在要求網址或 X-Goog-Api-Key 標頭中附加有效的 Google 地圖平台 API 金鑰：

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

2. OAuth 2.0 範圍

如果使用 OAuth 授權，系統支援下列範圍：

  • https://www.googleapis.com/auth/maps-platform.mapstools (建議)

要求驗證和限制

為避免負載過重並確保快速回應，系統會嚴格驗證批次要求：

  • 批次大小限制：這兩個 API 每項要求最多可包含 20 個項目。
  • ResolveNames 的必要條件：
    • 每個查詢項目都必須指定非空白的文字參數。
    • 查詢內容必須代表特定地點名稱或地址 (例如「Googleplex, Mountain View, CA」、「Eiffel Tower, Paris」)。
    • 不支援一般類別搜尋 (例如「紐約的餐廳」) 或不含位置資訊的通用連鎖店名稱 (例如「星巴克」)，這類搜尋可能無法解析。
  • ResolveMapsUrls 需求條件：
    • 每個網址都必須是結構有效的 Google 地圖網址。
    • 支援的格式包括：
      • 標準地點網址：https://www.google.com/maps/place/...
      • 縮短網址：https://maps.app.goo.gl/...
    • 不支援一般以查詢為依據的地圖網址 (例如 https://maps.google.com/?q=restaurant)，以及未指向單一不重複地點的網址。

處理部分錯誤

這兩個 API 都設計為批次處理器。如果批次中的部分項目無法解析，整體要求不會因頂層錯誤而失敗。API 會改為傳回「部分成功」回應。

如何解讀回應

  1. 保證 1:1 對應：傳回的結果 (適用於 ResolveNames) 或實體 (適用於 ResolveMapsUrls) 清單會與輸入清單 1:1 對應。
  2. 失敗時的空白元素：如果索引 i 的項目無法解析，結果清單會在索引 i 包含空白物件 {}。
  3. failedRequests Map：回應包含 failedRequests 對應。
    • key 是失敗項目的從 0 開始的索引 (以 JSON 中的字串表示)。
    • value 是 google.rpc.Status 物件，內含特定錯誤代碼 (來自標準 gRPC/HTTP 狀態) 和詳細訊息，說明失敗原因。

頂層失敗

只有在要求驗證失敗時 (例如傳遞超過 20 個項目，或缺少必填欄位)，才會傳回頂層 HTTP 錯誤 (例如 400 Bad Request)。

API 規格和 Curl 範例

1. ResolveNames API

方法：POST

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

要求主體格式

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (必要)：要解決的查詢清單 (最多 20 個)。
  • locationBias (選用)：可視區域定界框，可將結果偏向當地區域。
  • regionCode (選用)：CLDR 國家/地區代碼 (例如「US」、「FR」)，可讓結果偏向特定國家/地區。

Curl 範例：成功解決問題

這項查詢會解析「Googleplex」和「艾菲爾鐵塔」。

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"
JSON 回應
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Curl 範例：混合結果 (部分失敗)

在本例中，第一個項目是無法解析的垃圾文字，第二個項目則是有效地點。

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"
JSON 回應
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

方法：POST

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

要求主體格式

{
  "urls": [
    "string"
  ]
}
  • urls (必要)：要解析的 Google 地圖網址字串重複清單 (最多 20 個)。

Curl 範例：成功解決問題

解析標準的 Google 地圖地點連結。

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"
JSON 回應
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Curl 範例：混合結果 (部分失敗)

解決一個有效的地點網址和一個格式錯誤/不支援的網址。

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"
JSON 回應
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Curl 範例：驗證失敗

嘗試在單一要求中傳遞超過 20 個網址。

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"
JSON 回應
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}