適用於 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

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

以上範例將 0,0 的 lat/lng 設為查詢字串,但把地址做為查詢字串傳送。搜尋特定位置時,就不需要提供經緯度。不過,如果不知道確切的地址,則可以指定座標,調整搜尋的結果。舉例來說,執行地址搜尋「中山路」時,會傳回太多結果。

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)

除了街道地址或經緯度,您還可以使用 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 會要求在澳洲雪梨的塔龍加動物園即時導航:

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 都必須包含 cbllpanoid 參數。

  • cbll 接受以半形逗號分隔的經緯度值 (46.414382,10.013988),應用程式會顯示距離這個位置最近的全景。由於街景服務圖像會定期更新,且每次拍攝的位置可能略有不同,因此更新圖像後,拍攝地點可能會切換到不同的全景。

  • panoid 是特定的全景 ID。如果同時指定 panoidcbll,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 為垂直向上。

例子

以下舉例說明使用街景服務意圖。

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)

將金字塔納入街景服務