適用於 Android 的 Google 地圖意圖

Android 版 Google 地圖應用程式會公開多種意圖，可讓您在顯示、搜尋、導航或街景模式中啟動 Google 地圖。如果您想在應用程式中嵌入地圖，請參閱 Google 地圖 Android API 入門指南。

總覽

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

  1. Display a map at a specified location and zoom level.
  2. Search for locations or places, and display them on a map.
  3. Request directions from one location to another. 路線可傳回三種交通方式：開車、步行、單車。
  4. 在 Google 街景服務中顯示全景圖像。

本頁面說明您可在 Android 版 Google 地圖應用程式中使用的意圖。如果想進一步瞭解「意圖和意圖篩選器」，或是「Android 平台常見的意圖」，請參閱 Android 開發人員說明文件。

意圖要求

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

  • 動作：所有 Google 地圖意圖都會以 View 動作的形式呼叫 — ACTION_VIEW。
  • URI：Google 地圖意圖會使用已編碼的網址，指定所需動作，以及執行動作所需的部分資料。
  • 套件：呼叫 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 物件上呼叫 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 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);

Kotlin

// Creates an Intent that will load 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)

參數

除了用來顯示地圖的參數外，Google 搜尋還支援下列參數：

  • 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' will return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

Kotlin

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

在意圖 URI 中加入 lat/lng 會使結果偏向特定區域：

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 examples above

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 examples above

正在啟動即時路線導航

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

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

參數

  • q：設定導航搜尋的終點。這個值可以是緯度、經度座標或查詢格式化的地址。如果查詢字串傳回多個結果，系統會選取第一個結果。

  • mode 會設定運送方式。模式是選用項目，可以設為下列其中一個選項：

    • d (預設)：開車
    • b 適用於騎單車
    • l (機車)
    • 步行：w

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

前往塔龍加動物園的路線

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

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 度，正西為 270 度。傳遞給方位的值將會以相同方向納入；也就是 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 will angle 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 will angle 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)

街景服務中的金字塔