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/...
- 不支持基于查询的常规地图网址（例如 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)：重试请求。

将 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