本頁面由 Cloud Translation API 翻譯而成。

適用於 Android 的 Google 地圖意圖
透過集合功能整理內容你可以依據偏好儲存及分類內容。

Android 版 Google 地圖應用程式會公開多種意圖，可讓您在顯示、搜尋、導航或街景模式中啟動 Google 地圖。如要在應用程式中嵌入地圖，請參閱 Maps SDK for Android 快速入門導覽課程。

針對 Android Automotive OS (AAOS) 平台，您可以考量特定因素，並使用其他意圖。詳情請參閱 Android Automotive 意圖的 Google 地圖說明文件。

總覽

意圖可讓您在 Intent 物件中描述要執行的動作 (例如「顯示地圖」或「顯示前往機場的路線」)，藉此在其他應用程式中啟動活動。Android 版 Google 地圖應用程式支援數種不同的意圖，可讓您啟動 Google 地圖應用程式，並執行下列四種動作之一：

以指定位置和縮放等級顯示地圖。
搜尋地點或地點，並在地圖上顯示。
請求從一個地點前往另一個地點的路線。路線指引可針對三種交通工具傳回：開車、步行、騎單車。
在 Google 街景服務中顯示全景圖像。

本頁面說明您可在 Android 版 Google 地圖應用程式中使用的意圖。如要進一步瞭解意圖，請參閱「意圖和意圖篩選器」和「常見意圖」。

意圖要求

如要透過意圖啟動 Google 地圖，您必須先建立 Intent 物件，並指定其動作、URI 和套件。

動作：所有 Google 地圖意圖都會以 View 動作的形式呼叫 — ACTION_VIEW。
URI：Google 地圖意圖會使用網址編碼 URI，指定所選動作以及執行該動作所需的部分資料。
Package：呼叫 setPackage("com.google.android.apps.maps") 可確保 Android 版 Google 地圖應用程式處理意圖。如果未設定套件，系統會判斷哪些應用程式可以處理 Intent。如果有多個應用程式可供使用，系統可能會詢問使用者要使用哪個應用程式。

注意： 在 Android Automotive OS (AAOS) 上，也會使用套件名稱 com.google.android.apps.maps。不過，AAOS 有特定考量和額外意圖。如要進一步瞭解 AAOS 專屬行為和功能，請參閱 Android Automotive 專用 Google 地圖意圖說明文件。

建立 Intent 後，您可以要求系統以多種方式啟動相關應用程式。常見的做法是將 Intent 傳遞至 startActivity() 方法。系統會啟動必要的應用程式 (在本例中為 Google 地圖)，並啟動對應的 Activity。

Java

// Create a Uri from an intent string. Use the result to create an Intent.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
// 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);

Kotlin

// Create a Uri from an intent string. Use the result to create an Intent.
val gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988")
// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
// 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 物件上呼叫 resolveActivity()。如果結果非空值，至少會有一個應用程式可處理意圖，因此可以放心呼叫 startActivity()。如果結果為 null，請勿使用意圖，並盡可能停用叫用意圖的功能。

Java

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

Kotlin

mapIntent.resolveActivity(packageManager)?.let {
    ...
}

舉例來說，如要顯示舊金山的地圖，您可以使用下列程式碼：

Java

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
    startActivity(mapIntent);
}

Kotlin

val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
mapIntent.resolveActivity(packageManager)?.let {
    startActivity(mapIntent)
}

網址編碼查詢字串

傳遞至 Google 地圖意圖的所有字串都必須採用 URI 編碼。舉例來說，字串 1st & Pike, Seattle 應變更為 1st%20%26%20Pike%2C%20Seattle。字串中的空格可以使用 %20 編碼，也可以替換成加號 (+)。

您可以使用 android.net.Uri parse() 方法對字串進行編碼。例如：

Java

Uri gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));

Kotlin

val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"))

顯示地圖

使用 geo: 意圖，在指定位置和縮放等級顯示地圖。

geo:latitude,longitude?z=zoom

參數

latitude 和 longitude 可設定地圖的中心點。
z 可選設定地圖的初始縮放等級。可接受的值範圍為 0 (全世界) 到 21 (個別建築物)。上限可能會因所選位置的可用地圖資料而異。

範例

Java

// Creates an Intent that loads 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);

Kotlin

// Creates an Intent that loads a map of San Francisco
val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = 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
geo:0,0?q=latitude,longitude(label)

參數

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

q 會定義在地圖上醒目顯示的地點。所有搜尋要求都必須提供 q 參數。接受的位置可以是地點名稱或地址。字串應使用網址編碼，因此 City Hall, New York, NY 這類地址應轉換為 City+Hall,New+York,NY。
label 可讓您在地圖上指定的地點設定自訂標籤。label 必須指定為字串。

類別搜尋

如果您傳送一般搜尋字詞，Google 地圖會嘗試尋找符合您指定條件的經緯度附近位置。如果未指定位置，Google 地圖會嘗試尋找附近的產品資訊。例如：

Java

// 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);
// Search for restaurants in San Francisco.
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Search for restaurants nearby.
val gmmIntentUri = Uri.parse("geo:0,0?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Search for restaurants in San Francisco.
val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

您可以透過指定縮放參數和查詢字串，進一步調整搜尋結果。在下例中，新增 10 倍的縮放比例，嘗試在城市層級尋找餐廳，而非附近。

Java

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

Kotlin

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

地點搜尋

搜尋特定地址時，系統會在該位置顯示圖釘。

Java

Uri gmmIntentUri = Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
    Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

上述範例會設定 0 的緯度和經度，0，但會將地址做為查詢字串傳遞。搜尋特定地點時，系統不需要經緯度。不過，如果您不知道確切地址，可以嘗試指定座標，以便搜尋結果偏向某個方向。舉例來說，如果您搜尋「Main Street」這個地址，可能會傳回太多結果。

Java

// Searching for 'Main Street' returns too many results.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

Kotlin

// Searching for 'Main Street' returns too many results.
val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")

在意圖 URI 中加入經緯度會使結果偏向特定區域：

Java

// Searches for '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);

Kotlin

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

如果您知道搜尋結果會傳回單一值，建議您傳遞選用標籤。標籤必須以字串的形式指定，並顯示在地圖標記下方。請注意，只有在 q 指定為經緯度座標時，系統才會提供標籤。

Java

// Display a label at the location of Google's Sydney office.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=Google+Sydney@-33.8666,151.1957");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Display a label at the location of Google's Sydney office.
val gmmIntentUri =
    Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

除了街道地址或經緯度外，您也可以使用plus code，在已知位置顯示圖釘。

Java

// Display the location of Google, San Francisco using a global plus code.
Uri gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX");
// Equivalently, define the same location using a local plus code.
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco");
// Construct and use the Intent as in the preceding examples.

Kotlin

// Display the location of Google, San Francisco using a global plus code.
var gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX")
// Equivalently, define the same location using a local plus code.
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco")
// Construct and use the Intent as in the preceding examples.

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

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

參數

q：設定導覽搜尋的端點。這個值可以是經緯度座標或查詢格式化的地址。如果查詢字串傳回多個結果，系統會選取第一個結果。
mode 會設定運送方式。mode 為選用項目，可設為下列任一值：
- d (預設)：開車
- b 適用於騎單車
- l (機車)
- 步行：w
avoid 會設定路線應盡量避免的功能。avoid 為選用值，可設為下列一或多個值：
- t (收費路段)
- 高速公路占 h
- f 適用於渡輪

範例

以下 Intent 要求前往澳洲雪梨的塔龍加動物園 (Taronga Zoo)，並提供即時路線導航：

Java

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

Kotlin

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

前往塔龍加動物園的路線 — **圖 2.** 前往 Taronga Zoo 的路線

如果您不想支付通行費或搭乘渡輪，可以要求路線盡量避開這些項目。

Java

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

Kotlin

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

如果你想運動一下，可以改為要求單車路線。

Java

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

Kotlin

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

如果您偏好使用電動二輪車，可以要求路線包含汽車無法行駛的狹窄道路和小徑。以下 intent 會傳回印度的路線。

Java

Uri gmmIntentUri = Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

val gmmIntentUri =
    Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

顯示街景服務全景

使用 google.streetview 意圖啟動 Google 街景服務。Google 街景服務可讓您在涵蓋區域的指定地點進行全景檢視。您也可以查看使用者提供的 Photosphere 全景相片和街景服務特輯相片集。

google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt
google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt

參數

所有 google.streetview URI 都必須包含 cbll 或 panoid 參數：

cbll 會接受經緯度值，以逗號分隔 (46.414382,10.013988)。應用程式會顯示距離這個位置最近的全景相片。由於街景服務圖像會定期更新，且每次拍攝相片時拍攝位置可能會略有不同，因此圖像更新後，你的所在位置可能會連結至不同的全景圖。
panoid 是特定全景 ID。如果您同時指定 panoid 和 cbll，Google 地圖會使用全景 ID。Android 應用程式可透過 StreetViewPanoramaLocation 物件取得全景 ID。
cbp 是選用參數，可調整攝影機的初始方向。cbp 參數會接受 5 個以逗號分隔的值，所有值皆為選用。最有意義的值是第二、第四和第五個，分別用於設定方位、縮放和傾斜。系統不支援第一和第三個值，應將其設為 0。
- bearing：以度為單位，從正北方順時針測量相機的指南針方向。正北為 0 度，正東為 90 度，正南為 180 度，正西為
  1. 傳遞至方位角的值會重複，也就是 0°、360° 和 720° 都會指向相同方向。方向角的定義為五個以半形逗號分隔的值中的第二個。
- zoom：設定攝影機的縮放等級。預設的縮放等級設為 0。縮放等級 1 會將放大倍數加倍。縮放功能會在 0 和目前全景圖的最大縮放等級之間固定。也就是說，任何超出這個範圍的值都會設為範圍內最接近的極端值。舉例來說，-1 的值會設為 0。縮放值是五個以半形逗號分隔的值中的第四個。
- tilt：指定相機的角度 (向上或向下)。範圍介於 -90 到 0 和 0 到 90 之間；90 代表垂直向下、0 為水平置中、-90 為垂直向上。

範例

以下列舉幾個使用街景服務意圖的範例。

Java

// Displays an image of the Swiss Alps.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia.
Uri gmmIntentUri = Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter angles the camera slightly up, and towards the east.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Kotlin

// Displays an image of the Swiss Alps.
val gmmIntentUri =
    Uri.parse("google.streetview:cbll=46.414382,10.013988")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia.
val gmmIntentUri =
    Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter angles the camera slightly up, and towards the east.
val gmmIntentUri =
    Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

適用於 Android 的 Google 地圖意圖 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

意圖要求

Java

Kotlin

Java

Kotlin

Java

Kotlin

網址編碼查詢字串

Java

Kotlin

顯示地圖

Java

Kotlin

搜尋地點

類別搜尋

Java

Kotlin

Java

Kotlin

地點搜尋

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

啟動即時路線導航

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

顯示街景服務全景

Java

Kotlin

適用於 Android 的 Google 地圖意圖
透過集合功能整理內容你可以依據偏好儲存及分類內容。