適用於 Android 的 Google 地圖意圖

Android 版 Google 地圖應用程式提供數種意圖，可讓您在顯示、搜尋、導航或街景服務模式中啟動 Google 地圖。如果您想在應用程式中嵌入地圖，請參閱 Google Maps 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。

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

// 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，您不應使用該意圖，且應停用叫用意圖的功能。

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

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

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

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

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() 方法將字串編碼。例如：

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

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 (個別建築物)。視所選位置可用的地圖資料而定，上限可能有所不同。

例子

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

// 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 地圖就會嘗試尋找附近的商家資訊。例如：

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

// 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 時，系統會嘗試尋找城市層級的餐廳，而不是附近餐廳。

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

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)

搜尋地點

搜尋特定地址時，該地點會顯示圖釘。

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

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」(主要街道) 的地址搜尋時，會傳回過多結果。

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

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

在意圖 URI 中新增經緯度，即可根據特定區域調整結果：

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

// 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 指定為經緯度座標時，才能使用標籤。

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

// 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 在已知位置顯示圖釘。

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

// 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) 即時路線導航：

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

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)

如果您不想支付過路費或搭乘渡輪，可要求規劃行程以避免這些行程。

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

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)

如果您需要一些運動，可以改為要求騎腳踏車路線。

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

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 會傳回印度的路線。

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

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 到 90 之間；90 代表垂直向下、0 為水平置中、-90 為垂直向上。

例子

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

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

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