地圖工具解析度 API

Maps Tools Resolution API 是 Maps Grounding Lite 的一部分。這項 API 提供批次端點，可將位置名稱和 Google 地圖網址解析為 Google 地圖地點 ID。傳回的地點 ID 可與其他 Google Maps Platform API 搭配使用。每則回覆也包含一個連結，可將解析的地點儲存為 Google 地圖中的清單。

Resolution API 可透過 REST 方法和 Maps Grounding Lite MCP 伺服器上的工具使用：

功能 REST 方法 MCP 工具
將位置名稱或地址解析為地點 resolveNames resolve_names
將 Google 地圖網址解析為地點 resolveMapsUrls resolve_maps_urls

事前準備

如要使用 Resolution API，您必須擁有已啟用計費功能的 Google Cloud 雲端專案，並啟用 Maps Grounding Lite API 服務。如需操作說明，請參閱「在 Google Cloud 專案中啟用 Maps Grounding Lite 服務」。

API 存取權和驗證

Resolution API 支援 API 金鑰和 OAuth 2.0 憑證。

API 金鑰

如要驗證要求，請在 X-Goog-Api-Key 標頭中傳遞有效的 Google Maps Platform API 金鑰，或將金鑰附加至要求網址：

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

請將本頁範例中的 API_KEY 替換成您的 API 金鑰。

OAuth 2.0 範圍

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

  • https://www.googleapis.com/auth/maps-platform.mapstools

用量限制

Resolution API 適用下列預設配額：

  • ResolveNames：每項專案每分鐘 600 次查詢。
  • ResolveMapsUrls：每項專案每分鐘 600 次查詢。
  • 批次大小：每項要求最多 20 個查詢或網址。

無論要求包含多少項目，每項要求都算是一次查詢。

定價

向 ResolveNames 和 ResolveMapsUrls 提出的要求，會以 Places API Text Search Essentials (IDs Only) SKU 計費，費用為 $0 美元 (免付費)。與 Maps Grounding Lite 的其他部分一樣，您的專案必須有帳單帳戶。

要求驗證和限制

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

  • 批次大小限制：這兩種方法每次要求最多可處理 20 個項目。
  • ResolveNames 需求條件：
    • queries 中的每個項目都必須指定非空白的 text 參數。
    • 查詢必須代表特定地點名稱或地址 (例如「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) 和未指向單一特定地點的網址。

將解析的地點儲存至 Google 地圖

如果批次中至少有一個項目解析成功，回應就會包含 saveToMapsUrl 欄位。這是一個 Google 地圖連結，包含批次中所有成功解析的地點。如果使用者想將解析的地點儲存、分享或在 Google 地圖中以清單形式開啟，請向他們提供這個連結。

請一律使用 API 傳回的連結。請勿自行建構連結。如果批次中沒有任何項目解析，回應就不會包含 saveToMapsUrl。

處理部分錯誤

這兩種方法都是批次處理器。如果批次中的某些項目無法解析，整體要求不會失敗，也不會出現頂層錯誤。而是傳回部分成功回應，您必須檢查回應，找出個別項目失敗的原因。

解讀回應

  1. 保證 1:1 對應：傳回的 results 清單 (適用於 ResolveNames) 或 entities 清單 (適用於 ResolveMapsUrls) 會依索引與輸入清單 1:1 對應。
  2. 失敗時傳回空白元素：如果索引 i 的項目無法解析，結果清單會在索引 i 包含空白物件 {}。
  3. failedRequests 地圖：回應包含 failedRequests 地圖。
    • 鍵是以 0 為基礎的失敗項目索引 (在 JSON 中以字串表示)。
    • 這個值是 google.rpc.Status 物件，包含錯誤代碼和說明項目失敗原因的訊息。
  4. saveToMapsUrl 僅涵蓋成功項目：saveToMapsUrl 連結僅包含已解決的項目。不含失敗項目。

請勿假設整個批次都失敗，因為只有一個項目失敗。請務必查看 failedRequests，瞭解是否有無法解析的項目。

個別項目錯誤

下表列出您可能會在 failedRequests 中看到的個別項目錯誤：

方法 原因 程式碼 訊息
ResolveNames 無法將名稱或地址解析為地點。 5 (NOT_FOUND) Place not found.
ResolveMapsUrls 網址無法解析為地點。 3 (INVALID_ARGUMENT) Failed to resolve Maps URL to a place.
兩種方法 解析項目時發生內部錯誤。 13 (INTERNAL) Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

僅重試失敗的項目，並使用 INTERNAL。

頂層失敗

在下列情況下，API 會傳回頂層錯誤，而非部分回覆：

  • 要求無效 (400 INVALID_ARGUMENT)：要求包含超過 20 個項目、ResolveNames 要求沒有查詢或查詢的 text 值空白，或 ResolveMapsUrls 要求的網址空白或語法無效。只要有一個無效項目，整個要求就會失敗。
  • 驗證、權限或配額錯誤：例如 API 金鑰遺失或無效，或要求超出用量限制。
  • 伺服器錯誤 (500 INTERNAL)：請重試要求。

搭配使用 Resolution API 和 MCP

位於 https://mapstools.googleapis.com/mcp 的 Maps Grounding Lite MCP 伺服器會將 Resolution API 公開為兩項工具：

設定 LLM 使用 Maps Grounding Lite MCP 伺服器後，這些工具就會與其他 Maps Grounding Lite 工具一併提供。這些工具接受相同的輸入內容、強制執行相同的限制，並傳回與 REST 方法相同的部分失敗回應。

工具回應包含 save_to_maps_url 欄位。工具說明會指示 LLM，當使用者想將解析的地點儲存、分享或開啟為 Google 地圖中的清單時，應顯示這個連結，而非自行建構連結。

以下範例使用 curl 直接呼叫 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
}'

如要呼叫 resolve_maps_urls，請將 name 設為 resolve_maps_urls，並在 arguments 中傳遞 urls 陣列。

REST API 規格和 curl 範例

ResolveNames

方法：POST

https://mapstools.googleapis.com/v1: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/v1:resolveNames?key=API_KEY"
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"
}

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/v1:resolveNames?key=API_KEY"
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

方法：POST

https://mapstools.googleapis.com/v1: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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"
JSON 回應
{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

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

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

提供意見

如要回報問題或提供 Resolution API 相關意見，請使用 Maps Grounding Lite 公開 Issue Tracker 元件：