适用于 Android Automotive intent 的 Google 地图

通过 Android intent，您可以在 Android Automotive 版 Google 地图中启动导航。

注意： 使用第三方互操作性 API（与 Google 服务互动）需遵守 Google API 服务条款。确保您的申请符合所有适用的 Google 政策。

概览

本页介绍了可与 Google 地图 Android Automotive 版搭配使用的 intent。如需查看详细的 Android 开发者文档，请参阅以下内容：

• intent 和 intent 过滤器
• Android 平台通用的 intent

意图请求

如需使用 intent 启动 Android Automotive 版 Google 地图，您必须先创建一个 Intent 对象，并指定其操作、URI 和软件包。

• 操作。所有 Google 地图 intent 都作为 View 操作 ACTION_VIEW 调用。

• URI。Google 地图 intent 使用 URI 编码的字符串来指定所选操作，以及执行该操作所需的一些数据。

• 套餐。调用 setPackage("com.google.android.apps.maps") 可确保 Android 版 Google 地图应用处理该 intent。如果未设置软件包，系统会确定哪些应用可以处理该 intent。如果有多个应用可用，系统可能会询问您要使用哪个应用。

创建 Intent 后，您可以通过多种方式请求系统启动相关应用。一种常见的方法是将 intent 传递给 startActivity() 方法。系统会启动必要的应用（在本例中为 Google 地图），并启动相应的 Activity。

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

如果系统无法识别可以响应 intent 的应用，您的应用可能会崩溃。因此，在向用户显示这些 intent 之一之前，请先验证是否已安装接收应用。

如需验证是否有应用可以接收该 intent，请在 Intent 对象上调用 resolveActivity()。如果结果不为 null，则表示至少有一个应用可以处理该 intent，因此可以放心调用 startActivity()。如果结果为 null，您不应使用该 intent，并且应尽可能停用调用该 intent 的功能。

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

例如，如需启动前往悉尼塔龙加动物园的逐向导航，您可以使用以下代码：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

URI 编码的查询字符串

传递给 Google 地图 intent 的所有字符串都必须采用 URI 编码。例如，字符串“1st & Pike, Seattle”应变为 1st%20%26%20Pike%2C%20Seattle。字符串中的空格可以使用 %20 进行编码，也可以替换为加号 (+)。

您可以使用 android.net.Uri encode() 方法对字符串进行编码。例如：

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

显示地图

使用 geo: intent 可显示位于指定位置和缩放级别的地图。例如：

geo:latitude,longitude?z=zoom

参数

• latitude 和 longitude 用于设置地图的中心点。

• z 可选，用于设置地图的初始缩放级别。可接受的值范围为 0（整个世界）到 21（单个建筑物）。上限可能会因所选位置提供的地图数据而异。

示例

// Creates an intent that will load a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

搜索位置

使用此 intent 在指定视口内显示搜索查询：

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address

参数

除了用于显示地图的参数之外，搜索还支持以下参数：

• q 用于定义要在地图上突出显示的地点。所有搜索请求都必须提供 q 参数。它接受地点名称或地址形式的位置。该字符串应采用网址转义格式，因此“City Hall, New York, NY”之类的地址应转换为 City+Hall%2CNew+York%2CNY。

注意： 如果使用 q 参数 geo:0,0?q=query 指定了 intent URI，并且查询返回单个值，则查询结果会自动设置为目的地。

使用坐标自定义调整搜索结果

搜索非常具体的地理位置时，如果纬度和经度包含在 q 参数中，则不是严格必需的。不过，如果您不知道确切的地址或搜索查询不明确，可以尝试通过指定坐标来调整搜索结果。例如，对“Main Street”执行地址搜索可能会返回过多的结果：

// Searching for "101 Main Street" with no lat/long might return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

向 intent URI 添加纬度和经度会使结果偏向特定区域：

// Searches for "101 Main Street" near San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

沿路线搜索

如果在导航期间发送搜索 intent geo:latitude,longitude?q=query，系统会触发沿路线搜索，并忽略纬度和经度。

搜索预定义类别

为了支持与车辆的集成，车载 Google 地图支持显示以下预定义类别的 intent：

类别	intent 类别编码
加油站	gas_station
餐馆	restaurant
咖啡馆	cafe
停车	parking
电动车辆充电站	electric_vehicle_charging_station

类别 intent 的格式为 geo:lat,lng?c=category。

无论用户的语言区域设置如何，都使用 c=<pre-defined category>。 Google 地图会以适合相应类别的语言区域显示相关结果。例如：

// Search for gas stations nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?c=gas_station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

其他类别搜索

如果您在用户的语言区域设置中传递一般搜索字词（例如“餐厅”或“咖啡店”），Android Automotive 版 Google 地图会搜索符合条件的商家信息。如果 geo: intent 中提供了特定的纬度和经度，则搜索会以该位置为中心。如果未指定任何位置（例如，geo:0,0），Google 地图会尝试查找附近的商家信息。例如：

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

您还可以通过指定缩放参数以及查询字符串来进一步调整搜索结果的偏向。在以下示例中，添加 10 的缩放级别会尝试在城市级别而非附近查找餐厅：

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

启动精细导航

如需查看有关在其他 Android 设备上启动精细导航的文档，请参阅 Google 地图 Intent 中的 Android 精细导航。

使用此 intent 启动 Google 地图导航，并提供前往指定的一个或多个地址或坐标的精细导航。路线始终从用户的当前位置开始。

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

参数

如需启动导航，请使用 place 或 q，并根据需要添加 waypoints。如需选择性地将途经点标记为充电站，请参阅将电动汽车行程计划发送到 Google 地图。

• q 设置导航搜索的端点。可以是纬度和经度，也可以是格式正确的查询地址。如果它是返回多个结果的查询字符串，则会选择第一个结果。

• place 将终点设置为住址或工作地址。指定 home 可导航到用户住址，指定 work 可导航到用户工作场所。

• avoid 设置路线应尽量避开的功能。avoid 是可选项，可以设置为以下一个或多个值：

  • t 适用于收费站
  • h 为高速公路
  • f 适用于轮渡

• waypoints 用于指定一个或多个中间地点，以便将路线指引发送到 q 指定的最终目的地。您可以使用竖线字符 (|) 分隔地点来指定多个途经点，例如 Berlin,Germany|Paris,France。您可以根据需要使用任意数量的途经点。系统会按照网址中列出的顺序将途经点添加到路线中。每个途经点可以是地址，也可以是以英文逗号分隔的纬度和经度坐标；并且，您可以在同一 intent 中同时包含地址和纬度/经度坐标。字符串应采用 网址 转义，因此“Berlin,Germany|Paris,France”之类的途经点应转换为 Berlin%2CGermany%7CParis%2CFrance。

示例

此 intent 将请求前往澳大利亚悉尼塔龙加动物园的逐向导航：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

如果您不想支付过路费或乘坐渡轮，可以请求系统规划尽量避开这些情况的路线：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

或者，如果您想导航到住址，请使用：

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

如需按顺序启动前往以下三个地址的逐向导航，请将塔龙加动物园作为最终目的地 q，并将 Google 悉尼和悉尼歌剧院作为途经点：

1. Google 悉尼办事处

2. 悉尼歌剧院

3. 澳大利亚悉尼塔龙加动物园

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

与 q 类似，您可以使用以英文逗号分隔的纬度和经度来表示任何途经点，而不是使用地址。例如，如需启动相同的导航，同时传递悉尼歌剧院的纬度经度而非地址，请执行以下操作：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

将电动汽车行程规划发送到 Google 地图

使用此多目的地导航 intent 可将某些目的地指定为电动汽车 (EV) 充电站。此 intent 扩展了多途经点 intent，通过在电动汽车行程规划应用和 Google 地图之间同步充电站信息，帮助驾驶员保持足够的电动汽车电池电量，以便到达目的地。

注意： 如需将任何途经点标记为充电站，路线必须包含至少一个途经点和最终目的地。

对于充电站，出行意图：

• 必须包含名称和经纬度
• 可选择性地包含功率输出，用于计算充电时间

Google 会使用充电站名称和纬度/经度来查找匹配的充电站地点，以显示丰富的充电站数据，例如连接器类型、总数、速度和实时可用性、支持的付款方式以及主机兴趣点 (POI)。例如，导航最后一段的室外停车场内的驾车路线、营业时间、评分。为确保充电站与 Google 的数据匹配良好，请使用特定的 <brand name>，例如 ChargePoint。

参数

您可以使用以下参数指定最终目的地和所有途经点的详细信息，包括指定为电动汽车充电站的途经点。

最终目的地

如需将充电站设为最终目的地，请使用：

• q：必须包含充电站的经纬度值。
• q_type：1 表示最终目的地是充电站。
• q_name：最终目的地的名称。如果 q_type 为 1，则必须提供此值。
• q_power_output_kw：充电站功率输出（以千瓦为单位）的双精度数。可选。

路径点

对于途经点，所有参数都是以竖线 (�3) 分隔的并行数组，其中的值与途经点顺序相同，但不包括最终目的地。 |如果并行数组中的元素数量不匹配，系统会将其视为格式有误的 intent。

如需添加一个或多个充电站途经点，请使用以下参数，所有参数均为可选。如果某个目的地标记为充电站，则必须为该目的地指定途经点名称。

• waypoints：如精细导航 intent 中所述的途径点列表。必须是充电站途经点的经纬度值。

• waypoint_types：每个途经点的类型，以数字形式指定。 0 是任意经停点（默认值），1 是充电站。

• waypoint_names：途经点名称。对于充电站，此字段是必填字段。

• waypoint_power_outputs_kw：充电站功率（以千瓦为单位）的双精度数。对于充电站，您可以选择性地指定途经点的功率输出值，如果找不到匹配的充电站，系统会使用该值作为回退值。空 slot 表示未提供任何值。

用户体验 (UX) 行为

对于包含多个目的地的出行意图，系统会显示路线概览界面，但不会自动开始导航。

对于格式正确的 intent，Google 地图将显示相应行程的路线概览界面。路线概览界面将显示 intent 中的所有途经点和最终目的地，并提供充电建议（如适用）。

对于标记为充电站的任何途经点或最终目的地，Google 地图会在 Google 的数据库中搜索匹配的地点。为确保显示尽可能准确的充电站信息，请执行以下操作：

• 如果找到匹配项，Google 地图会使用 Google 数据在界面 (UI) 中显示充电站，并为该充电站提供充电建议。

• 如果未找到匹配项，系统会使用 intent 中提供的充电站数据（纬度/经度、名称和功率输出）在界面中显示此充电站，并提供在此充电站充电的建议。

示例

以下示例说明了如何针对各种电动汽车出行规划场景构建 intent，包括通过多个充电站导航和处理未知的功率输出。

通过多个充电站导航到最终目的地

以下 intent 会通过两个充电站（ChargePoint 和 Evie）导航到最终目的地新南威尔士州麦格理港。

目标平台（按顺序）：

1. ChargePoint 充电站（位置：-32.9599188,151.6240806，功率输出：6.6 千瓦）

2. Evie 充电站（位置：-31.9432539,152.4699808，功率输出：350 千瓦）

3. 新南威尔士州麦格理港

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

未知功率输出

如果功率输出值未知，请将 waypoint_power_outputs_kw 的相关 slot 留空。或者，如果所有 slot 均为空，则无需指定 waypoint_power_outputs_kw 参数。

目标平台（按顺序）：

1. ChargePoint 充电站（位置：-32.9599188,151.6240806，功率输出：未知）

2. 新南威尔士州麦格理港

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

将最终目的地标记为充电站

如需将最终目的地标记为充电站，请指定 q_type、q_name 和 q_power_output_kw 参数。

目标平台（按顺序）：

1. 澳大利亚悉尼塔龙加动物园

2. ChargePoint 充电站（位置：-32.9599188,151.6240806，功率输出：未知）

3. Evie 充电站（位置：-31.9432539,152.4699808，功率输出：350 千瓦）

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

操作 intent

以下是可用的含界面的操作 intent：

操作	说明
geo.action:?act=mute	将所有导航语音播报静音。
geo.action:?act=unmute	取消导航语音导航的静音。
geo.action:?act=show_traffic	在地图上显示路况线。
geo.action:?act=hide_traffic	隐藏地图上的路况线条。
geo.action:?act=show_satellite	在地图上显示卫星图像。
geo.action:?act=hide_satellite	隐藏地图上的卫星图像。
geo.action:?act=show_alternates	Google 地图会打开替代路线界面（仅在导航时有效）。
geo.action:?act=query_next_turn	Google 地图会播报下一处转弯（仅在导航时有效）。
geo.action:?act=distance_to_next_turn	Google 地图会播报到下一处转弯的距离（仅在导航时有效）。
geo.action:?act=time_to_next_turn	Google 地图会播报到达下一处转弯的时间（仅在导航时有效）。
geo.action:?act=distance_to_destination	Google 地图会播报目的地距离（仅在导航时有效）。
geo.action:?act=go_back	Google 地图会返回到界面中的上一个屏幕。
geo.action:?act=query_current_road	Google 地图会读出当前道路。
geo.action:?act=query_destination	Google 地图会语音播报目的地。
geo.action:?act=traffic_report	Google 地图会播报路况信息。
geo.action:?act=clear_search_results	Google 地图会关闭搜索结果界面（如果该界面处于打开状态）。
geo.action:?act=apply_electric_vehicle_connector_filter	为电动车辆充电站搜索结果应用连接器类型过滤条件。
geo.action:?act=remove_electric_vehicle_connector_filter	移除电动车辆充电站搜索结果的连接器类型过滤条件。
geo.action:?act=apply_electric_vehicle_payment_filter	为电动车辆充电站搜索结果应用付款过滤器。
geo.action:?act=remove_electric_vehicle_payment_filter	移除电动车辆充电站搜索结果的付款过滤条件。
geo.action:?act=apply_electric_vehicle_fast_charging_filter	为电动车辆充电站搜索结果应用快速充电过滤器。
geo.action:?act=remove_electric_vehicle_fast_charging_filter	移除了电动车辆充电站搜索结果的快速充电过滤条件。
geo.action:?act=avoid_tolls	如果用户正在导航，则告知 Google 地图避开收费路线。 如果当前路线有收费站，系统可能会重新规划路线。
geo.action:?act=allow_tolls	如果用户正在导航，则告知 Google 地图允许包含收费站的路线。 如果允许收取过路费可以获得更好的路线，系统可能会重新规划路线。
geo.action:?act=avoid_ferries	如果用户正在导航，则告知 Google 地图避开有渡轮的路线。如果当前有效路线包含渡轮，这可能会导致重新规划路线。
geo.action:?act=allow_ferries	如果用户正在导航，则告知 Google 地图允许包含渡轮的路线。如果允许使用渡轮可以获得更好的路线，系统可能会重新规划路线。
geo.action:?act=avoid_highways	如果用户正在导航，则告知 Google 地图避开包含高速公路的路线。如果当前有效路线包含高速公路，这可能会导致系统重新规划路线。
geo.action:?act=allow_highways	如果用户正在导航，则告知 Google 地图允许包含高速公路的路线。如果允许使用高速公路可以找到更好的路线，系统可能会重新规划路线。
geo.action:?act=eta	如果用户正在导航，Google 地图会播报目的地的预计到达时间（例如上午 9:15）。
geo.action:?act=time_to_destination	如果用户正在导航，Google 地图会播报到达目的地的预计时间（例如 15 分钟）。
geo.action:?act=exit_navigation	退出导航。
geo.action:?act=select_search_result&id=0	如果屏幕上显示了搜索结果（如随附图片所示），此操作会根据提供的 ID 参数开始导航到第 n 个结果。请注意，索引从 0 开始（也就是说，geo.action:?act=select_search_result&id=0 将选择列表中的第一个结果）。

注意： 您可以使用 Google Automotive 模拟器来测试这些 intent。