Maps Tools Resolution API（实验性）

Maps Tools Resolution API 提供批量处理端点，用于将位置名称和网址解析为 Google 地图地点 ID。

API 访问权限和身份验证

身份验证方式

这些 API 同时支持 API 密钥和 OAuth 2.0 凭据：

1. API 密钥

您可以通过将有效的 Google Maps Platform API 密钥附加到请求网址或 X-Goog-Api-Key 标头中来对请求进行身份验证：

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. OAuth 2.0 范围

如果使用 OAuth 授权，则支持以下范围：

  • https://www.googleapis.com/auth/maps-platform.mapstools（推荐）

请求验证和限制

为防止过载并确保快速响应，系统会对批处理请求进行严格验证：

  • 批处理大小限制：这两个 API 都允许每个请求最多包含 20 个项目。
  • ResolveNames 要求：
    • 每个 queries 项都必须指定一个非空文本参数。
    • 查询必须表示特定的地点名称或地址（例如“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）以及未指向单个唯一地点的网址。

处理部分错误

这两个 API 均设计为批处理程序。如果批次中的某些项无法解析，则整个请求不会因顶级错误而失败。而是返回部分成功响应。

如何解读响应

  1. 保证 1:1 对齐：返回的结果（对于 ResolveNames）或实体（对于 ResolveMapsUrls）列表与输入列表的映射为 1:1。
  2. 失败时的空元素：如果索引为 i 的项无法解析，结果列表将在索引 i 处包含一个空对象 {}。
  3. failedRequests Map：响应包含一个 failedRequests 映射。
    • 键是失败项的从 0 开始的索引（在 JSON 中表示为字符串）。
    • 值是一个 google.rpc.Status 对象，其中包含特定的错误代码（来自标准 gRPC/HTTP 状态）和详细的消息，用于说明失败原因。

顶级故障

仅当请求未通过验证（例如，传递的商品数量超过 20 件或缺少必需字段）时，才会返回顶级 HTTP 错误（例如 400 Bad Request）。

API 规范和 Curl 示例

1. ResolveNames API

方法：POST

https://mapstools.googleapis.com/v1alpha: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/v1alpha:resolveNames?key=KEY"
JSON 响应
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

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/v1alpha:resolveNames?key=KEY"
JSON 响应
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

方法：POST

https://mapstools.googleapis.com/v1alpha: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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON 响应
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
JSON 响应
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

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