適用於 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 街景服務中顯示全景圖像。

本頁面說明可搭配 Google 地圖應用程式使用的意圖 Android。如要進一步瞭解意圖和意圖，請參閱這篇文章 篩選器，或 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)

如果系統無法識別可回應意圖的應用程式，就會啟動您的應用程式 可能會當機因此，您應該先確認接收 應用程式會先安裝，再向使用者呈現這些意圖。

如要確認應用程式是否可接收意圖，請呼叫 您的 resolveActivity() Intent 物件。如果結果為非空值，則至少有一個應用程式可處理 您可以放心呼叫 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)

正在搜尋舊金山的餐廳

您還可以指定 zoom 參數，進一步調整搜尋結果。 字串。在下方範例中，將縮放比例增加 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，但會傳送地址做為查詢 字串。搜尋非常明確的位置時，會顯示經緯度 不需要。不過，如果您不知道確切的地址， 指定座標，藉此調整搜尋結果。適用對象 例如，搜尋「中街」的地址搜尋會傳回過多 也就是預測結果

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 中加入經緯度，即可根據特定 區域：

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。Google 地圖會使用全景圖 ID， panoid 和 cbll 皆有指定全景 ID Android 應用程式 StreetViewPanoramaLocation 物件。

  • cbp 是選用參數，可調整 相機cbp 參數會使用 5 個以半形逗號分隔的值， 則為選用項目。最重要的值是第二、第四和第五 可分別設定方位、縮放和傾斜功能。第一個和第三項 值不支援，因此應設為 0。

    • bearing：指出相機的指南針方向 (以度為單位) 從北美開始正北為 0 度，正東為 90 度，正南為 180 度，正西為 270 度。值 通過光圈會結束；等於 0°、360° 和 720° 往相同方向移動三個點方位的定義是 以半形逗號分隔的值。
    • zoom：設定相機的縮放等級。已設定預設縮放等級 0。縮放 1 會導致放大倍率。不會縮放。 介於 0 到目前全景的最大縮放等級之間。 也就是說，凡是落在這個範圍之外的值都會設為 落在範圍內最接近的極端。例如 設為 0。縮放是五個逗號分隔值的第四個值。
    • tilt：指定攝影機的角度 (向上或向下)。範圍是 -90 介於 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)

街景服務中的金字塔