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 版 Google 地圖應用程式中使用的意圖。如要進一步瞭解意圖與意圖篩選器Android 平台常見的意圖,請參閱 Android 開發人員說明文件。

意圖要求

如要使用意圖啟動 Google 地圖,您必須先建立 Intent 物件,並指定其動作、URI 和套件。

  • 動作:所有 Google 地圖意圖都稱為「檢視」動作 - 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 & amp; 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

參數

  • latitudelongitude 可設定地圖的中心點。
  • 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)

上述範例將 lat/lng 設定為 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)

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

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 會要求前往澳洲雪梨的塔倫加動物園提供行車路線導航:

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 街景服務可讓您在其涵蓋區域提供指定地點的全景。您也可以使用使用者提供的 Photopheres街景服務特殊集錦

google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt
google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt

參數

所有 google.streetview URI 都必須包含 cbllpanoid 參數。

  • cbll 接受以逗號分隔值 (46.414382,10.013988) 的緯度和經度。應用程式會顯示這個位置最靠近的全景相片。由於街景服務圖像會定期更新,而且每次拍攝的位置可能會略有不同,因此當圖像更新時,您的拍攝地點可能會以不同拍攝方式貼齊。

  • panoid 是特定的全景 ID。如果同時指定了 panoidcbll,Google 地圖就會使用全景 ID。來自 StreetViewPanoramaLocation 物件的 Android 應用程式可以使用全景 ID。

  • cbp 是可調整相機初始方向的選用參數。cbp 參數採用 5 個以逗號分隔的值,這些都是選用值。最重要的值是第二個值、第四個和第五個,分別設定軸承、縮放和傾斜。系統不支援第一個和第三個值,因此應設為 0

    • bearing:表示從北方順時針角度拍攝相機的指南針方向。正北 0 度,東方 90 度,南南 180 度,西方 270 度。傳遞至方位的值會包裝;也就是說,0°、360° 和 720° 都是指向相同方向的所有點。航向定義為五個逗號分隔值的第二個。
    • zoom:設定相機的縮放等級。預設的縮放等級設定為 0。縮放倍率為 1,可以放大兩倍。目前全景的縮放比例可介於 0 和最大縮放等級之間。這表示超出此範圍的任何值都會設為落在這個範圍內的最極端值。例如,-1 的值將設為 0。縮放是 5 個逗號分隔值的第四個。
    • tilt:指定相機的角度 (向上或向下)。範圍介於 -90 到 0 和 0 到 90 之間;90 代表垂直向下、0 為水平置中、0 為垂直向上。

範例

以下是使用街景服務意圖的範例。

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)

街景服務金字塔