Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

Maps Tools Resolution API

Maps Tools Resolution API 是 Maps Grounding Lite 的一部分。它提供批量端点，可将地点名称和 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 个搜索查询或网址。

无论请求包含多少项内容，都算作一次查询。

价格

根据 Places API 文本搜索要素版（仅 ID）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 map：响应包含 failedRequests map。
- 键是失败项的从 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 搭配使用

位于 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 公开问题跟踪器组件：

Maps Tools Resolution 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 响应

发送反馈

Maps Tools Resolution API