適用於 Android 的 Google 地圖意圖

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

對於 Android Automotive OS (AAOS) 平台，有特定的考量事項和額外的意圖。詳情請參閱「Google 地圖 Android Automotive 版意圖」說明文件。

總覽

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

  1. 顯示指定位置和縮放等級的地圖。
  2. 搜尋地點，並在地圖上顯示。
  3. 要求從某個地點前往另一個地點的路線。路線指引可支援三種交通方式：開車、步行和騎單車。
  4. 在 Google 街景服務中顯示全景圖像。

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

意圖要求

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

  • 動作：所有 Google 地圖意圖都會以 View 動作呼叫 - ACTION_VIEW。
  • URI：Google 地圖意圖會使用網址編碼 URI，指定所選動作，以及執行動作所需的資料。

  • 套件：呼叫 setPackage("com.google.android.apps.maps") 可確保 Android 版 Google 地圖應用程式處理意圖。如果未設定套件，系統會判斷哪些應用程式可以處理 Intent。如果有多個應用程式可用，系統可能會詢問使用者要使用哪個應用程式。

建立 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 前，請先確認已安裝接收應用程式。

如要確認應用程式是否可接收意圖，請在 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 地圖 Intent 的所有字串都必須經過 URI 編碼。舉例來說，字串 1st & Pike, Seattle 應會變成 1st%20%26%20Pike%2C%20Seattle。字串中的空格可以編碼為 %20，或以加號 (+) 取代。

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

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)
搜尋舊金山的餐廳
圖 1. 搜尋「舊金山的餐廳」

您可以指定縮放參數和查詢字串，進一步調整搜尋結果。在下列範例中，新增 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=-33.8666,151.1957(Google+Sydney)");
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 要求會啟動前往澳洲雪梨塔龍加動物園的逐向導航：

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. 前往塔龍加動物園的路線

如果不想支付過路費或搭乘渡輪，可以要求路線盡量避開這些路段。

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 街景服務可在涵蓋範圍內，提供指定地點的全景檢視畫面。此外，您也可以查看使用者提供的全景相片和街景服務特別收藏。

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)
街景服務中的金字塔
圖 3. 街景服務中的金字塔