搜索商家信息

借助 search_places 工具，LLM 可以根据自然语言查询在 Google 地图上查找地点。该工具会返回 AI 生成的匹配地点摘要。对于摘要中引用的每个地点，它还会返回地点 ID、经纬度坐标、Google 地图链接和提供方。

您可以通过 MCP 服务器或作为 searchText REST 方法调用 search_places。本页面介绍了请求选项（包括 Pro 选项）、响应包含的内容以及请求的结算方式。如需查看完整架构，请参阅 search_places MCP 参考文档和 searchText REST 参考文档。

请求选项

LLM 在调用工具时，会根据用户请求和工具说明设置这些选项。您可以使用自己的指令来影响模型使用的选项；请参阅控制 Pro 使用情况。

下表介绍了 search_places 的请求选项：

选项	说明
`text_query`	必需。搜索查询，例如 `coffee shops near Golden Gate Park`。查询必须包含足够的位置信息，以便明确无误，或者请求必须包含 `location_bias`。
`location_bias`	一个圆形区域（`center` 和可选的 `radius_meters`，最大 50,000 米），用于使结果偏向于该区域。如果 `text_query` 指定了明确的位置，则系统会改用该位置。
`language_code`	摘要的语言，例如 `en` 或 `ja`。默认语言为英语。
`region_code`	用户的 CLDR 地区代码，例如 `US`。会影响特定区域的地名，并可能根据适用法律影响结果。
`page_size`	要返回的地点数量上限。默认值为 5。6 到 10 的值属于 Pro 选项。如果值大于 10，则会返回 `INVALID_ARGUMENT` 错误。服务返回的地点数量可能少于请求的数量。
`include_extended_details`	如果为 `true`，则摘要包含扩展地点详情。这是专业版选项。默认设置为 `false`。

Pro 选项

两个选项均选择 Maps Grounding Pro SKU。使用其中一项或两项功能的请求将按 Pro SKU 计费：

Pro 选项	适用情形
`include_extended_details` 设置为 `true`	用户的请求需要扩展地点详情，例如评价中的数据分析、菜单亮点、氛围或游客提示。
`page_size`（从 6 到 10）	用户想要比较 5 个以上的地点。

不使用这两个选项的请求（包括 page_size 为 1 到 5 的请求）将按 Essentials SKU 结算。

扩展地点详情

当用户的请求需要定性数据分析、实时条件或专业属性时，请将 include_extended_details 设置为 true，例如：

评价者的反馈：基于评价的分析洞见、客户情绪和反馈。
具体推介项目：菜单项、菜肴、特色食品、饮料或商家亮点。
氛围：室内装饰、美学风格、环境或氛围。
实用的游客提示：是否需要提前预订、到店政策、等待时间、地点繁忙程度、停车和设施。
邻近性：当用户询问附近或最近的地点时，系统会根据查询位置或 location_bias 中心点，计算距离或行程时间。

摘要中的数据洞见取决于查询以及每个地点的可用数据。并非每种数据分析类型都会出现在每个回答中。

对于标准搜索（菜系或商店类型、地址、联系信息、营业时间和标准设施），请将其保留为 false（默认值）。包含扩展详细信息的请求需要更长时间才能完成。

扩展详细信息不会更改响应的结构。如果没有这些参数，摘要会用一两句话描述每个地点。借助这些模型，每个地点都会获得更长的说明，这些说明会利用更多 Google 地图数据，包括来自评价的数据洞见。两个 SKU 的结构化 places 条目相同。

示例

以下 MCP 请求会要求提供最多 8 个地点的详细信息。它按 Pro SKU 计费：

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

以下示例向 searchText REST 方法发送相同的请求：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

将 API_KEY 替换为您的 API 密钥。

如果没有扩展详情，摘要会用一两句话描述每个地点：

Example Trattoria [0]（4.6★ (1,250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$）烛光摇曳、私密温馨的餐厅，评论者称其浪漫，但周末会比较喧闹。特色菜肴包括肉酱意面、布拉塔奶酪和提拉米苏。建议提前预订；周五和周六晚上，未预约的顾客可能需要等待 30-45 分钟，且路边停车位有限。

响应

响应包含以下字段：

summary：搜索结果的自然语言摘要。它可能包含从零开始的引用（例如 [0]），这些引用会映射到 places 中的条目。
places[]：摘要中提及的地点。每个地点都包含：
- place：地点的资源名称，格式为 places/{id}。
- id：地点 ID。您可以将其与其他 Google Maps Platform API 搭配使用，例如在地图上显示地点。
- location：地点的纬度/经度坐标。
- googleMapsLinks：指向地点 (placeUrl)、路线 (directionsUrl)、评价 (reviewsUrl)、照片 (photosUrl) 和撰写评价 (writeAReviewUrl) 的 Google 地图链接。
- attribution：您必须随地点一起显示的提供方说明。请参阅提供出处的要求。
contentToken：智能体数据可视化令牌（预览版），可让您使用 Places UI Kit 在回答中显示地点，而无需支付额外费用。当响应中包含至少一个地点时返回。

对于这两种 SKU 以及 MCP 和 REST，响应具有相同的结构。如需了解字段详情，请参阅 search_places 参考文档。

结算和配额

每个 search_places 请求都是一个可结算事件：

不使用任何 Pro 选项的请求将按Maps Grounding Essentials SKU 计费。
使用 Pro 选项的请求会按 Maps Grounding Pro SKU 计费。在同一请求中同时使用这两个选项不会改变费用。如需了解 Pro 价格，请参阅比较 Essentials、Pro 和 Grounding with Google Maps。

如果您使用 Places UI Kit 显示 search_places 响应中的地点，则可以使用智能体数据可视化令牌（预览版），这样这些 Places UI Kit 请求就不会被计费。

search_places 配额为每个项目每分钟 300 次查询，由两个 SKU 共享。如需了解价格，请参阅主价格表和印度价格表。