適用於 Android Automotive 意圖的 Google 地圖

透過 Android Intent，您可以在 Android Automotive 啟動 Google 地圖導航。

注意： 使用第三方互通性 API (與 Google 服務互動) 時，須遵守《Google API 服務條款》。確認您的應用程式符合所有適用的 Google 政策。

總覽

本頁說明可搭配 Android Automotive 版 Google 地圖使用的意圖。如需詳細的 Android 開發人員說明文件，請參閱下列內容：

• 意圖和意圖篩選器
• Android 平台通用的意圖

意圖要求

如要透過意圖啟動 Android Automotive 版 Google 地圖，請先建立 Intent 物件，並指定其動作、URI 和套件。

• 動作。所有 Google 地圖意圖都會以 View 動作呼叫， ACTION_VIEW。

• URI。Google 地圖意圖會使用URI 編碼字串，指定所選動作，以及執行動作所需的資料。

• 套裝組合。呼叫 setPackage("com.google.android.apps.maps") 可確保 Android 版 Google 地圖應用程式處理 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 物件上呼叫 resolveActivity()。如果結果不是空值，表示至少有一個應用程式可以處理意圖，因此可以放心呼叫 startActivity()。如果結果為空值，您就不應使用意圖，並盡可能停用叫用該意圖的功能。

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 地圖意圖的所有字串都必須經過 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: 意圖，在地圖上顯示指定位置和縮放等級。例如：

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);

搜尋地點

使用這項意圖，在指定的可視區域內顯示搜尋查詢：

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

參數

除了用於顯示地圖的參數外，搜尋也支援下列參數：

• q 會定義要在地圖上醒目顯示的地點。所有搜尋要求都必須提供 q 參數。這項功能接受地點名稱或地址。字串應經過網址逸出處理，因此「City Hall, New York, NY」這類地址應轉換為 City+Hall%2CNew+York%2CNY。

注意： 如果意圖 URI 是以 q 參數 geo:0,0?q=query 指定，且查詢只傳回單一值，系統會自動將查詢結果設為目的地。

使用座標調整搜尋結果

搜尋非常具體的位置時，如果 q 參數中包含經緯度，則不一定需要提供經緯度。不過，如果您不知道確切地址或查詢內容模稜兩可，可以指定座標，嘗試調整搜尋結果。舉例來說，搜尋「中正路」可能會傳回過多結果：

// 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);

在意圖 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);

沿路線搜尋

如果在導航期間傳送搜尋意圖 geo:latitude,longitude?q=query，系統會沿著路線搜尋，並忽略經緯度。

搜尋預先定義的類別

為支援與車輛整合，車輛版 Google 地圖支援可顯示下列預先定義類別的意圖：

類別	意圖類別編碼
加油站	gas_station
餐廳	restaurant
咖啡廳	cafe
停車場	parking
電動車充電站	electric_vehicle_charging_station

類別意圖的格式為 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 Auto 版 Google 地圖會搜尋符合條件的商家資訊。如果 geo: 意圖中提供特定經緯度，搜尋範圍會以該位置為中心。如果沒有指定位置 (例如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 裝置上啟動即時路線導航，請參閱「在 Android 適用的 Google 地圖 Intent 中啟動即時路線導航」。

使用這個意圖啟動 Google 地圖導航功能，並取得前往一或多個指定地址或座標的即時路線指引。系統一律會從使用者目前所在位置提供路線。

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

參數

如要啟動導覽功能，請使用 place 或 q，並視需要搭配 waypoints。如要選擇性地將中途點標示為充電站，請參閱「將電動車行程計畫傳送至 Google 地圖」一文。

• q 設定導航搜尋的端點。可以是經緯度或格式正確的地址查詢。如果是傳回多個結果的查詢字串，系統會選取第一個結果。

• place 可將終點設為住家或公司。指定「住家」即可導航至使用者的住家，指定「公司」即可導航至使用者的工作地點。

• avoid 會設定路線應盡量避開的特徵。avoid 為選填欄，可以設為一或多個值：

  • t 過路費
  • h 高速公路
  • f 渡輪

• waypoints 指定一或多個中途地點，以便將路線導向 q 指定的最終目的地。如要指定多個中途點，請使用直立線字元 (|) 分隔地點，例如 Berlin,Germany|Paris,France。你可以視需要使用任意數量的途經點。系統會按照網址中列出的順序，將途中的航點加入路線。每個中途點可以是地址，也可以是逗號分隔的緯度和經度座標；而且，您可以在同一個意圖中同時使用地址和緯度/經度座標。字串應為網址逸出，因此「Berlin,Germany|Paris,France」這類的中途點應轉換為 Berlin%2CGermany%7CParis%2CFrance。

範例

這項意圖會要求前往澳洲雪梨塔龍加動物園的逐向導航：

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 Sydney 和雪梨歌劇院則設為途經點，請傳遞下列參數：

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 地圖

使用這項多目的地導覽意圖，將部分目的地指定為電動車充電站。這項意圖是多個途中的停靠點意圖的延伸功能，可同步電動車行程規劃應用程式和 Google 地圖的充電站資訊，協助駕駛人維持足夠的電動車電池電量，順利抵達目的地。

注意： 如要將任何中途點標示為充電站，路線必須包含至少一個中途點和最終目的地。

充電站、行程意圖：

• 必須包含名稱和經緯度
• 可選擇性包含功率輸出，用於計算充電時間

Google 會使用充電站名稱和經緯度，找出相符的充電站地點，並顯示豐富的資料，例如接頭類型、總數、速度和即時可用性、支援的付款方式，以及主機興趣點 (POI)。例如，導航最後一段的戶外停車場行車路線、營業時間、評分。為確保充電站與 Google 的資料相符，請使用特定 <brand name>，例如 ChargePoint。

參數

您可以使用下列參數指定最終目的地和任何途中的航點 (包括指定為電動車充電站的航點) 詳細資料。

最終目的地

如要將充電站設為最終目的地，請使用：

• q：必須包含充電站的經緯度值。
• q_type：1 指定最終目的地為充電站。
• q_name：最終目的地的名稱。如果 q_type 為 1，則為必要欄位。
• q_power_output_kw：充電站的功率輸出 (以千瓦為單位)，為雙精度浮點數。選用項目。

路線控點

如果是中途點，所有參數都是以管道分隔 (|) 的值陣列，與中途點的順序相同，但不包括最終目的地。如果平行陣列中的元素數量不符，系統會將其視為格式錯誤的意圖。

如要新增一或多個充電站航點，請使用下列參數 (全為選用)。如果其中一個目的地標示為充電站，則該目的地必須有中途點名稱。

• waypoints：如即時路線導航意圖所述的途經點清單。充電站航點必須是經緯度值。

• waypoint_types：每個途中的類型，以數字表示。 0 為任何停靠站 (預設值)，1 為充電站。

• waypoint_names：路線點名稱。這是充電站的必填欄位。

• waypoint_power_outputs_kw：充電站功率的雙倍數字 (以千瓦為單位)。如果是充電站，您可以選擇指定航點電力輸出值，如果找不到相符的充電站，系統會改用這個值。空白插槽表示未提供任何值。

使用者體驗 (UX) 行為

如果行程意圖有多個目的地，系統會顯示路線總覽畫面，但不會自動啟動導航。

如果意圖格式正確，Google 地圖會顯示行程的路線總覽畫面。路線總覽畫面會顯示意圖中的所有途經點和最終目的地，並在適用情況下提供充電建議。

如果將充電站設為中途點或最終目的地，Google 地圖會在 Google 資料庫中搜尋相符地點。為確保充電站顯示最佳資訊：

• 如果找到相符的充電站，Google 地圖就會在使用者介面 (UI) 中顯示該充電站，並提供充電建議。

• 如果找不到相符的充電站，系統就會使用意圖中提供的充電站資料 (經緯度、名稱和功率輸出)，在使用者介面中顯示該充電站，並提供充電建議。

範例

以下範例說明如何為各種電動車行程規劃情境建構意圖，包括透過多個充電站導航，以及處理不明的電力輸出。

透過多個充電站導航至最終目的地

下列意圖會透過兩個充電站 (ChargePoint 和 Evie) 前往最終目的地，即新南威爾斯州麥覺理港。

目的地順序：

1. ChargePoint 充電站 (位置：-32.9599188,151.6240806，輸出功率：6.6kw)

2. Evie 充電站 (位置：-31.9432539,152.4699808，功率輸出：350kw)

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 的相關位置留空。或者，如果所有時段都為空白，則不需要指定 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，功率輸出：350kw)

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);

動作意圖

以下是可用的動作意圖和介面：

動作	說明
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 Emulator 測試這些意圖。