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

地圖工具解析度 API

Maps Tools Resolution API 是 Maps Grounding Lite 的一部分。這項服務提供批次端點，可將地點名稱和 Google 地圖網址解析為 Google 地圖地點 ID。您可以將傳回的地點 ID 用於其他 Google 地圖平台 API。每則回覆也包含連結，可將已解析的地點儲存為 Google 地圖中的清單。

Resolution API 提供 REST 方法和 Maps Grounding Lite MCP 伺服器上的工具：

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

事前準備

如要使用 Resolution API，您需要啟用帳單功能的 Google 雲端專案，以及啟用的 Maps Grounding Lite API 服務。如需操作說明，請參閱「在 Google Cloud 專案中啟用 Maps Grounding Lite 服務」。

API 存取權和驗證

解析度 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 個查詢或網址。

無論要求包含多少項目，都會計為一次查詢。

定價

系統會根據 Places API Text Search Essentials (IDs Only) SKU，針對 ResolveNames 和 ResolveMapsUrls 的要求免付費 ($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/...
- 系統不支援一般查詢型 Google 地圖網址 (例如 https://maps.google.com/?q=restaurant) 和未指向單一專屬地點的網址。

將已解決的地點儲存至 Google 地圖

如果批次中至少有一個項目可解析，回應會包含 saveToMapsUrl 欄位。這個 Google 地圖連結包含批次中所有已成功解決的地點。向想在 Google 地圖中儲存、共用或開啟已解析地點清單的使用者提供這個連結。

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

處理部分錯誤

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

解讀回應

保證 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)：重試要求。

搭配 MCP 使用 Resolution API

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

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

設定 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 元件：

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

事前準備

API 存取權和驗證

API 金鑰

OAuth 2.0 範圍

用量限制

定價

要求驗證和限制

將已解決的地點儲存至 Google 地圖

處理部分錯誤

解讀回應

每項商品的錯誤

頂層失敗

搭配 MCP 使用 Resolution API

REST API 規格和 curl 範例

ResolveNames

方法：POST

要求主體格式

Curl 範例：成功解析

JSON 回應

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

JSON 回應

ResolveMapsUrls

方法：POST

要求主體格式

Curl 範例：成功解析

JSON 回應

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

JSON 回應

Curl 範例：驗證失敗

JSON 回應

提供意見

地圖工具解析度 API