MCP Reference: mapstools.googleapis.com

当用户请求查找地点、商家、地址、位置、地图注点或任何其他与 Google 地图相关的搜索时，请调用此工具。

输入要求（至关重要）：

1. text_query（字符串 - 必填）：主要搜索查询。此参数必须明确定义用户要查找的内容。

   • 示例：'restaurants in New York'、'coffee shops near Golden Gate Park'、'SF MoMA'、'1600 Amphitheatre Pkwy, Mountain View, CA, USA'、'pets friendly parks in Manhattan, New York'、'date night restaurants in Chicago'、'accessible public libraries in Los Angeles'。
   • 对于特定地点详情：添加请求的属性（例如 'Google Store Mountain View opening hours'、'SF MoMa phone number'、'Shoreline Park Mountain View address'）。

2. location_bias（对象 - 可选）：使用此参数可优先显示特定地理区域附近的结果。

   • 格式：{"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
   • 用法：
     • 如需将偏向范围设为 5 公里半径，请使用以下代码：{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
     • 如需强烈偏向中心点：{"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}}（省略 radius_meters）。

3. language_code（字符串 - 可选）：用于显示搜索结果摘要的语言。

   • 格式：由两个字母组成的语言代码 (ISO 639-1)，后跟一个下划线和由两个字母组成的国家/地区代码 (ISO 3166-1 alpha-2)，例如 en、ja、en_US、zh_CN、es_MX。如果未提供语言代码，结果将以英语显示。

4. region_code（字符串 - 可选）：用户的 Unicode CLDR 地区代码。此参数用于显示地点详情，例如特定于区域的地点名称（如果有）。根据适用法律，该参数可能会影响结果。

   • 格式：双字母国家/地区代码 (ISO 3166-1 alpha-2)，例如 US、CA。

5. page_size（整数 - 可选）：要返回的地点数量上限，范围为 1 到 10。默认值为 5。仅当用户想要比较 5 个以上的地点时，才应将此值设置为 5 以上；6 到 10 之间的值会导致费用更高、延迟时间更长。

6. include_extended_details（布尔值 - 可选）：如果用户请求需要丰富的定性数据洞见、实时动态或专门的实体属性，请将此字段设置为 true。此字段的默认值为 false。如果将此值设置为 true，则会产生更高的费用和延迟时间。

工具调用说明：

• 位置信息（关键）：搜索查询必须包含足够的位置信息。如果位置不明确（例如，仅为“披萨店”），您必须在 text_query 中指定位置（例如，“纽约的披萨店”）或使用 location_bias 参数。如有必要，请添加城市、州/省/自治区/直辖市和国家/地区名称，以消除歧义。

• 始终提供尽可能具体且上下文丰富的 text_query。

• 仅在明确提供坐标或从用户已知情境推断位置信息是适当且必要的（为了获得更好的结果）时，才使用 location_bias。

• 必须使用 attribution 字段中的信息（如有）将接地输出归因于来源。

计算出发地和目的地之间的行程路线，可选择经过中间停靠点。返回每条路线的距离和时长。

输入要求（至关重要）：

1. origin 和 destination（对象 - 必需）：每个对象都必须使用以下其中一种方式提供：

   • address（字符串，例如 'Eiffel Tower, Paris'）。系统会直接解析命名的地点、地标和商家，因此请勿仅为了对航点进行地理编码而先调用 search_places。包括用户提到的任何城市、地区或国家。
   • lat_lng（对象，{"latitude": number, "longitude": number}）。
   • place_id（字符串，例如 'ChIJOwE_Id1w5EAR4Q27FkL6T_0'），例如来自 search_places。

2. intermediate_waypoints（对象数组 - 可选）：在出发地和目的地之间按顺序经过的最多 25 个经停点。格式与 origin 相同。TRANSIT 不支持此功能。仅包含用户要求的经停点；指定超过 10 个中间航点会导致费用增加和延迟时间延长。

3. travel_mode（枚举 - 可选）：DRIVE（默认）、WALK、BICYCLE 或 TRANSIT。

4. 时间（可选 - 最多设置一个）：采用 RFC 3339 时间戳格式，带有 UTC 偏移量，例如 '2026-09-19T08:00:00-07:00'。默认设置为立即出发。对于 TRANSIT，时间可以是过去 7 天内或未来 100 天内的某个时间。对于其他模式，时间最多可以是未来 365 天，且不能是过去的时间。

   • departure_time：在用户说出他们何时离开时使用（例如，“明天早上 8 点”）。
   • arrival_time：当用户说出他们必须到达的时间（例如“上午 9 点前到”）时使用。

5. routing_preference（枚举 - 可选）：

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE（默认）：忽略实时路况、异常路况和封路情况。延迟时间最短。
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL：使用实时路况信息（如有）。WALK 或 BICYCLE 不支持此方法。仅当用户询问路况、拥堵情况或根据路况调整后的预计到达时间时，才设置此参数。这会产生更高的费用和延迟时间。

6. location_bias（对象 - 可选）：{"latitude": number, "longitude": number}，用于消除航点地址中地名的歧义。如果名称不明确（例如“Springfield”），并且用户未提供区域，请保留 address 中给出的名称，并将 location_bias 设置为目标区域，而不是猜测区域。

7. compute_alternative_routes（布尔值 - 可选）：仅当用户询问路线选项或备选路线时，才设置为 true。默认值为 false，仅返回推荐路线。

8. include_polyline（布尔值 - 可选）：仅在需要路线几何图形 (encoded_polyline) 时设置为 true。默认值为 false。

工具调用说明：

• 如果缺少出发地或目的地，您必须先请用户澄清，然后再调用该工具。
• 对于“A 距离 B 有多远？”这类问题，请将 B 用作 origin，将 A 用作 destination。

工具调用示例：{"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":[{"address":"Louvre Museum"}],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

Instructions for Response:

• 请求备选路线时，系统会按照推荐程度从高到低的顺序排列路线。
• 如果 routes 为空，请告知用户未找到路线。请勿猜测路线。
• 如需查找 DRIVE 路线沿途的地点，请将路线的 retrieval_token 传递给 search_along_route。令牌的有效期为 10 分钟。
• 仅陈述工具返回的事实。请勿编造精细导航、公交线路、车站、站台或换乘信息。
• 必须使用每个路线的 attribution 字段（如果可用）将接地输出归因于来源。

当用户想要查找旅行路线沿途的地点、商家或地图注点（例如“去太浩湖路上的加油站”“旧金山和圣何塞之间的咖啡店”）时，请调用此工具。调用此工具的费用高于 search_places，因此在搜索单个地点附近（而非沿路线）时，请改用 search_places。

输入要求（至关重要）：

1. text_query（字符串 - 必填）：对沿途搜索内容的自然语言描述。

   • 示例：'ev chargers'、'coffee'、'vegetarian restaurants'、'rest stops'。

2. 路线规范（必填 - 仅提供以下其中一项）：

   • retrieval_token（字符串）：先前针对 DRIVE 路线调用 compute_routes 返回的 retrieval_token。只要路线已计算完毕，就首选此方法。令牌的有效期为 10 分钟。
   • route_endpoints（对象）：路线的 origin 和 destination。每个都必须使用 address、lat_lng 或 place_id 之一提供。
     • 示例： {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
   • encoded_polyline（字符串）：表示 DRIVE 路线的编码多段线。

3. travel_mode（枚举 - 可选）：DRIVE（默认）、WALK 或 BICYCLE。WALK 和 BICYCLE 仅支持 route_endpoints。不支持 TRANSIT。

4. routing_preference（枚举 - 可选）：

   • ROUTING_PREFERENCE_TRAFFIC_UNAWARE（默认）：在不考虑实时路况的情况下计算路线和绕行路线。延迟时间最短。
   • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL：使用实时路况信息（如有）。WALK 或 BICYCLE 不支持此方法。仅当用户询问路况、拥堵情况或根据路况调整的绕行时间时，才设置此参数。它会产生更高的延迟。

5. include_extended_details（布尔值 - 可选）：仅当请求需要定性评价数据分析、特定菜单项或产品/服务、氛围、访客提示或繁忙程度、电动汽车充电桩可用性、油价或其他丰富的定性详细信息时，才设置为 true。此字段的默认值为 false。启用此功能可能会增加延迟时间。

6. language_code（字符串 - 可选）：结果摘要和地点详情的语言，例如 en、ja、en-US。默认值为 en-US。

7. region_code（字符串 - 可选）：用户的 Unicode CLDR 区域代码，例如 US、CA。

工具调用说明：

• 每个结果都包含一个 detour_summary（如果可用），用于说明在该地点停留所产生的额外距离 (localized_detour_distance) 和额外时间 (detour_duration)（除非路线指定为 encoded_polyline）。您可以使用它来比较各种选项。
• 回答 summary 可能包含从零开始的引用（例如“[0]”），这些引用指向 results 中的条目。
• 必须使用每个 results[].place 的 attribution 字段（如果可用）将接地输出归因于来源。

将特定位置查询（地标名称或确切地址）的批量列表解析为规范的 Google 地图地点 ID。

输入要求（至关重要）：

1. queries（对象数组 - 必填）：要解析的位置查询列表。您最多可以指定 20 个查询。

   • 每个查询对象都必须具有：
     • text（字符串 - 必填）：表示要解析的特定地点名称或地址的文本查询。
       • 示例：'Googleplex, Mountain View, CA'、'1600 Amphitheatre Pkwy, Mountain View, CA'、'Eiffel Tower, Paris'。

2. location_bias（对象 - 可选）：使用此参数可优先显示特定地理区域附近的结果。

   • 格式：{"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

3. region_code（字符串 - 可选）：用户的 Unicode CLDR 地区代码（两个字母的国家/地区代码，例如 US、CA），用于使结果偏向该地区。

工具调用说明：

• 具体性（关键）：查询必须代表具体的地点名称或地址。不支持 'restaurants' 等宽泛搜索或 'Starbucks' 等连锁店名称。
• 如果您计划调用的下游工具已经直接接受原始地址或地点名称字符串，请勿调用此工具。

保存到 Google 地图：

• 回答中包含一个 save_to_maps_url 字段：一个 Google 地图链接，其中包含所有成功解析的地点。
• 当用户想要在 Google 地图中将解析后的地点保存、分享或打开为列表时，请向用户显示此链接。请勿自行构建此链接。

错误处理（关键）：

• 这是一款批处理工具。请求可能会返回“混合结果”（例如，某些查询成功解析，而其他查询失败）。
• results 的输出列表保证与输入 queries 索引一一对应。如果查询失败，则会在 results 列表中的相应索引处生成一条空的 Result 消息（未设置 entity）。
• 您必须检查响应中的 failed_requests 映射字段，以确定具体是哪个查询索引失败。failed_requests 的键表示请求中失败查询的索引（从 0 开始）。请勿因部分失败而认为整个批量调用都失败了。

将 Google 地图网址列表解析为规范的 Google 地图地点 ID。

何时调用此工具（至关重要）：

• 当用户提供一个或多个 Google 地图分享链接或网址（例如“https://maps.app.goo.gl/…”）时，请使用此工具。“https://www.google.com/maps/place/…”或“https://maps.google.com/…”），并且您需要提取底层规范地点 ID。
• 您最多可以在一个批量请求中指定 20 个要解析的网址。

输入要求（至关重要）：

• urls（字符串数组 - 必填）：要解析的 Google 地图网址列表。每个网址都必须是有效的单地点 Google 地图网址。

保存到 Google 地图：

• 回答中包含一个 save_to_maps_url 字段：一个 Google 地图链接，其中包含所有成功解析的地点。
• 当用户想要将解析出的地点保存、分享或在 Google 地图中以列表形式打开时（例如，收集对话中分享的地点），请向用户显示此链接。请勿自行构建此链接。

错误处理（关键）：

• 这是一款批处理工具。请求可能会返回“混合结果”（例如，某些网址成功解析，而其他网址解析失败）。
• entities 的输出列表保证与输入 urls 索引一一对应。网址解析失败会导致 entities 列表中相应索引处的 Entity 消息为空（未设置任何字段）。
• 您必须检查响应中的 failed_requests 映射字段，以确定具体是哪个网址索引失败。failed_requests 的键表示请求中失败网址的索引（从 0 开始）。请勿因部分失败而认为整个批量调用都失败了。