適用於 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 地圖意圖會使用已編碼的網址，指定所需動作，以及執行動作所需的部分資料。
• Package：呼叫 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)

參數

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

• q 會定義在地圖上要醒目顯示的地點。所有搜尋要求都必須使用 q 參數。它接受的位置可以是地點名稱或地址。字串應採用 網址編碼，因此像是「City Hall, New York, NY」的地址應轉換為 City+Hall,New+York,NY。

• label 可讓您在地圖上指定的地點設定自訂標籤。label 必須指定為字串。

類別搜尋

如果您傳送一般搜尋字詞，Google 地圖會嘗試在您指定的 lat/lng 附近尋找符合條件的地點。如果未指定位置，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 的 lat/lng，但會將地址做為查詢字串傳遞。搜尋特定地點時，不需要提供經緯度。不過，如果您不知道確切地址，可以嘗試指定座標，以便搜尋結果偏向特定位置。舉例來說，如果您搜尋「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 中加入 lat/lng 會使結果偏向特定區域：

// 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 指定為 lat/lng 座標時，系統才會提供標籤。

// 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 會要求逐轉導航至澳洲雪梨的塔龍加動物園：

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 街景服務可讓您在涵蓋區域的指定地點查看全景。您也可以查看使用者提供的 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 度，正西為 270 度。傳遞至方位角的值會重疊，也就是說，0°、360° 和 720° 都指向相同方向。方位角是五個以半形逗號分隔的值中的第二個。
  • zoom：設定攝影機的縮放等級。預設的縮放等級為 0。縮放 1 會將放大倍數加倍。縮放功能會在 0 和目前全景圖的最大縮放等級之間夾持。也就是說，超出這個範圍的任何值都會設為範圍內最接近的極端值。舉例來說，-1 的值會設為 0。縮放值是五個以半形逗號分隔的值中的第四個。
  • tilt：指定相機的角度 (向上或向下)。範圍介於 -90 到 0 和 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)