升級至 Pro SKU，即可使用更多地圖體驗代理工具功能！瞭解 Pro

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

地圖工具解析度 API

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

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

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

事前準備

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

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 Experiments 代理工具一樣，您的專案必須有帳單帳戶。

要求驗證和限制

為避免負載過重並確保快速回應，系統會根據下列規則驗證批次要求：

批次大小限制：這兩種方法在每個要求中最多允許 20 個項目。
ResolveNames 需求條件：
- queries 中的每個項目都必須指定非空白的 text 參數。
- 查詢必須代表特定地點名稱或地址，例如 "Googleplex, Mountain View, CA" 或 "Eiffel Tower, Paris"。
- 系統不支援一般類別搜尋 (例如 "restaurants in New York") 或不含地點的一般連鎖店名稱 (例如 "Starbucks")，且可能無法解析。
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 對應：傳回的 results 清單 (適用於 ResolveNames) 或 entities 清單 (適用於 ResolveMapsUrls) 會依索引與輸入清單 1:1 對應。
失敗時傳回空白元素：如果索引 i 的項目無法解析，結果清單會在索引 i 包含空白物件 {}。
failedRequests 地圖：回應包含 failedRequests 地圖。
- 鍵是以 0 為基礎的失敗項目索引 (在 JSON 中以字串表示)。
- 這個值是 google.rpc.Status 物件，包含錯誤代碼和說明項目失敗原因的訊息。
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

Maps Experiments 代理工具 MCP 伺服器位於 https://mapstools.googleapis.com/mcp，會將 Resolution API 公開為兩項工具：

resolve_names：將一批地點名稱或地址解析為地點 ID。
resolve_maps_urls：將一批 Google 地圖網址解析為地點 ID。

設定 LLM 使用 MCP 伺服器後，這些工具就會與其他 Maps Experience 代理工具一併提供。這些工具接受相同的輸入內容、強制執行相同的限制，並傳回與 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 Experience 代理工具公開 Issue Tracker 元件：

地圖工具解析度 API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

API 存取權和驗證

API 金鑰

OAuth 2.0 範圍

用量限制

定價

要求驗證和限制

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

處理部分錯誤

解讀回應

各項目的錯誤

頂層失敗

搭配使用 Resolution API 和 MCP

REST API 規格和 curl 範例

ResolveNames

方法：POST

要求主體格式

Curl 範例：成功解析

JSON 回應

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

JSON 回應

ResolveMapsUrls

方法：POST

要求主體格式

Curl 範例：成功解析

JSON 回應

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

JSON 回應

Curl 範例：驗證失敗

JSON 回應

提供意見

地圖工具解析度 API