Android 版 Google 地圖意圖

Google 地圖應用程式 Android 版提供多個意圖，您可以使用這些意圖在顯示、搜尋、導航或街景服務模式中啟動 Google 地圖。如要在應用程式中嵌入地圖，請參閱 Google Maps Android API 入門指南。

總覽

意圖可讓您在 Intent 物件中說明要執行的簡單動作 (例如「顯示地圖」或「顯示機場的路線」)，在其他應用程式中啟動活動。Google 地圖應用程式 Android 版支援多種不同的意圖，讓您啟動 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 地圖意圖稱為「瀏覽動作」。ACTION_VIEW。
• URI：Google 地圖意圖採用網址編碼功能指定需要的動作，以及部分要執行動作的資料。
• 套件：呼叫 setPackage("com.google.android.apps.maps") 可確保 Google 地圖應用程式 Android 版會處理意圖。如未設定套件，系統會判斷哪些應用程式可處理 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")

將 lat/lng 新增至意圖 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)

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

// 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 街景服務可讓您在整個涵蓋的區域，查看指定地點的全景。此外，您也可以使用使用者提供的照片，以及街景服務特別集錦。

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。Zoom 是五個半形逗號分隔的值的第四個。
  • 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)