Intent Google Maps untuk Android

Aplikasi Google Maps untuk Android mengekspos beberapa intent yang dapat Anda gunakan untuk meluncurkan Google Maps dalam mode tampilan, penelusuran, navigasi, atau Street View. Untuk menyematkan peta di aplikasi Anda, lihat Panduan memulai Maps SDK for Android.

Untuk platform Android Automotive OS (AAOS), ada pertimbangan khusus dan intent tambahan yang tersedia. Lihat dokumentasi Intent Google Maps untuk Android Automotive guna mengetahui detail selengkapnya.

Ringkasan

Intent memungkinkan Anda memulai aktivitas di aplikasi lain dengan menjelaskan tindakan yang ingin dilakukan (seperti "menampilkan peta" atau "menampilkan rute ke bandara") dalam objek Intent. Aplikasi Google Maps untuk Android mendukung beberapa intent yang berbeda,sehingga Anda dapat meluncurkan aplikasi Google Maps dan melakukan salah satu dari empat tindakan berikut:

  1. Menampilkan peta di lokasi dan tingkat zoom yang ditentukan.
  2. Menelusuri lokasi atau tempat, dan menampilkannya di peta.
  3. Meminta rute dari satu lokasi ke lokasi lain. Rute dapat ditampilkan untuk tiga moda transportasi: mengemudi, berjalan kaki, bersepeda.
  4. Menampilkan gambar panorama di Google Street View.

Halaman ini menjelaskan intent yang dapat Anda gunakan dengan aplikasi Google Maps untuk Android. Untuk mengetahui informasi selengkapnya tentang intent, lihat Intent dan filter intent serta Intent umum.

Permintaan intent

Untuk meluncurkan Google Maps dengan intent, Anda harus membuat Intent objek terlebih dahulu, dengan menentukan tindakan, URI, dan paketnya.

  • Tindakan: Semua intent Google Maps dipanggil sebagai tindakan Lihat — ACTION_VIEW.
  • URI: Intent Google Maps menggunakan URI yang dienkode URL yang menentukan tindakan yang dipilih, beserta beberapa data yang digunakan untuk melakukan tindakan tersebut.

  • Paket: Memanggil setPackage("com.google.android.apps.maps") memastikan bahwa aplikasi Google Maps untuk Android menangani Intent. Jika paket tidak ditetapkan, sistem akan menentukan aplikasi mana yang dapat menangani Intent. Jika beberapa aplikasi tersedia, pengguna mungkin akan ditanya aplikasi mana yang ingin digunakan.

Setelah membuat Intent, Anda dapat meminta sistem untuk meluncurkan aplikasi terkait dengan beberapa cara. Metode umum adalah meneruskan Intent ke startActivity() metode. Sistem akan meluncurkan aplikasi yang diperlukan — dalam hal ini Google Maps — dan memulai yang sesuai 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)

Jika sistem tidak dapat mengidentifikasi aplikasi yang dapat merespons intent, aplikasi Anda mungkin akan mengalami error. Oleh karena itu, verifikasi terlebih dahulu bahwa aplikasi penerima telah diinstal sebelum Anda menampilkan salah satu intent ini kepada pengguna.

Untuk memverifikasi bahwa aplikasi tersedia untuk menerima intent, panggil resolveActivity() pada objek Intent Anda. Jika hasilnya bukan null, berarti ada setidaknya satu aplikasi yang dapat menangani intent dan aman untuk memanggil startActivity(). Jika hasilnya adalah null, jangan gunakan intent dan, jika memungkinkan, nonaktifkan fitur yang memanggil intent.

Java

if (mapIntent.resolveActivity(getPackageManager()) != null) {
    ...
}

Kotlin

mapIntent.resolveActivity(packageManager)?.let {
    ...
}

Misalnya, untuk menampilkan peta San Francisco, Anda dapat menggunakan kode berikut:

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

String kueri yang dienkode URL

Semua string yang diteruskan ke Intent Google Maps harus dienkode URI. Misalnya, string 1st & Pike, Seattle harus menjadi 1st%20%26%20Pike%2C%20Seattle. Spasi dalam string dapat dienkode dengan %20 atau diganti dengan tanda plus (+).

Anda dapat menggunakan metode encode() android.net.Uri untuk mengenkode string. Contoh:

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

Menampilkan peta

Gunakan intent geo: untuk menampilkan peta di lokasi dan tingkat zoom yang ditentukan.

geo:latitude,longitude?z=zoom

Parameter

  • latitude dan longitude menetapkan titik pusat peta.
  • z secara opsional menetapkan tingkat zoom awal peta. Nilai yang diterima berkisar dari 0 (seluruh dunia) hingga 21 (bangunan individual). Batas atas dapat bervariasi bergantung pada data peta yang tersedia di lokasi yang dipilih.

Contoh

Java

// Creates an Intent that loads 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 loads 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)

Menelusuri lokasi

Gunakan intent ini untuk menampilkan kueri penelusuran dalam area tampilan yang ditentukan. Jika kueri memiliki satu hasil, Anda dapat menggunakan intent ini untuk menampilkan pin di tempat atau alamat tertentu, seperti landmark, bisnis, fitur geografis, atau kota.

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address
geo:0,0?q=latitude,longitude(label)

Parameter

Selain parameter yang digunakan untuk menampilkan peta, Penelusuran mendukung parameter berikut:

  • q menentukan tempat yang akan ditandai di peta. Parameter q diperlukan untuk semua permintaan Penelusuran. Parameter ini menerima lokasi sebagai nama tempat atau alamat. String harus dienkode URL, sehingga alamat seperti City Hall, New York, NY harus dikonversi menjadi City+Hall,New+York,NY.

  • label memungkinkan Anda menetapkan label kustom di tempat yang diidentifikasi di peta. label harus ditentukan sebagai String.

Jika Anda meneruskan istilah penelusuran umum, Google Maps akan mencoba menemukan lokasi di dekat garis lintang dan bujur yang Anda tentukan yang sesuai dengan kriteria Anda. Jika tidak ada lokasi yang ditentukan, Google Maps akan mencoba menemukan listingan terdekat. Contoh:

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)
Mencari Restoran di San Francisco
Gambar 1. Menelusuri Restoran di San Francisco

Anda dapat lebih memprioritaskan hasil penelusuran dengan menentukan parameter zoom bersama dengan string kueri. Pada contoh berikut, menambahkan zoom 10 akan mencoba menemukan restoran di tingkat kota, bukan di sekitar.

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)

Menelusuri alamat tertentu akan menampilkan pin di lokasi tersebut.

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)

Contoh sebelumnya menetapkan garis lintang dan bujur 0,0, tetapi meneruskan alamat sebagai string kueri. Saat menelusuri lokasi tertentu, garis lintang dan bujur tidak diperlukan. Namun, jika tidak mengetahui alamat persisnya, Anda dapat mencoba memprioritaskan hasil penelusuran dengan menentukan koordinat. Misalnya, melakukan penelusuran alamat untuk 'Main Street' mungkin akan menampilkan terlalu banyak hasil.

Java

// Searching for 'Main Street' returns too many results.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

Kotlin

// Searching for 'Main Street' returns too many results.
val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")

Menambahkan garis lintang dan bujur ke URI intent akan memprioritaskan hasil ke area tertentu:

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)

Jika mengetahui bahwa penelusuran Anda menampilkan satu nilai, Anda mungkin ingin meneruskan label opsional. Label harus ditentukan sebagai String dan muncul di bawah penanda peta. Perhatikan bahwa label hanya tersedia jika q ditentukan sebagai koordinat garis lintang dan bujur.

Java

// Display a label at the location of Google's Sydney office.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)");
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)

Sebagai alternatif untuk alamat jalan atau garis lintang dan bujur, Anda dapat menampilkan pin di lokasi yang diketahui menggunakan Plus Codes.

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 preceding examples.

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 preceding examples.

Meluncurkan navigasi belokan demi belokan

Gunakan URI intent ini untuk meluncurkan navigasi Google Maps dengan petunjuk arah belokan demi belokan ke alamat atau koordinat yang ditentukan. Petunjuk arah selalu diberikan dari lokasi pengguna saat ini.

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude

Parameter

  • q: Menetapkan endpoint untuk penelusuran navigasi. Nilai ini dapat berupa koordinat garis lintang dan bujur atau alamat berformat kueri. Jika berupa string kueri yang menampilkan lebih dari satu hasil, hasil pertama akan dipilih.

  • mode menetapkan metode transportasi. mode bersifat opsional dan dapat ditetapkan ke salah satu opsi berikut:

    • d untuk mengemudi (default)
    • b untuk bersepeda
    • l untuk motor
    • w untuk berjalan kaki

  • avoid menetapkan fitur yang harus dihindari oleh rute. avoid bersifat opsional dan dapat ditetapkan ke satu atau beberapa opsi berikut:

    • t untuk tarif tol
    • h untuk jalan raya
    • f untuk kapal feri

Contoh

Intent berikut meminta navigasi belokan demi belokan ke Kebun Binatang Taronga, di Sydney, Australia:

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)
Rute ke Taronga Zoo
Gambar 2. Rute ke Kebun Binatang Taronga

Jika tidak ingin membayar tarif tol atau naik kapal feri, Anda dapat meminta perutean yang mencoba menghindari fitur tersebut.

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)

Jika ingin berolahraga, Anda dapat meminta petunjuk arah bersepeda.

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)

Jika ingin menggunakan motor, Anda dapat meminta petunjuk arah yang menyertakan jalan dan jalur sempit yang tidak dapat dilalui mobil. intent berikut menampilkan rute di India.

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)

Menampilkan panorama Street View

Gunakan intent google.streetview untuk meluncurkan Google Street View. Google Street View memberikan tampilan panorama dari lokasi yang ditentukan di seluruh area cakupannya. Foto 360 yang dikontribusikan pengguna, dan koleksi khusus Street View juga tersedia.

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

Parameter

Semua URI google.streetview harus menyertakan parameter cbll atau panoid:

  • cbll menerima garis lintang dan bujur sebagai nilai yang dipisahkan koma (46.414382,10.013988). Aplikasi ini menampilkan panorama yang difoto paling dekat dengan lokasi ini. Karena gambar Street View diperbarui secara berkala, dan foto mungkin diambil dari posisi yang sedikit berbeda setiap kali, lokasi Anda mungkin akan beralih ke panorama lain saat gambar diperbarui.

  • panoid adalah ID panorama tertentu. Google Maps menggunakan ID panorama jika panoid dan cbll ditentukan. ID panorama tersedia untuk an aplikasi Android dari objek StreetViewPanoramaLocation.

  • cbp adalah parameter opsional yang menyesuaikan orientasi awal kamera. Parameter cbp memerlukan 5 nilai yang dipisahkan koma, yang semuanya bersifat opsional. Nilai yang paling signifikan adalah nilai kedua, keempat, dan kelima yang menetapkan arah, zoom, dan kemiringan. Nilai pertama dan ketiga tidak didukung, dan harus ditetapkan ke 0.

    • bearing: menunjukkan arah kompas kamera dalam derajat searah jarum jam dari Utara. Utara sejati adalah 0, timur 90, selatan 180, dan barat
      1. Nilai yang diteruskan ke arah akan digabungkan; yaitu, 0°, 360°, dan 720° semuanya mengarah ke arah yang sama. Arah didefinisikan sebagai nilai kedua dari lima nilai yang dipisahkan koma.
    • zoom: Menetapkan tingkat zoom kamera. Tingkat zoom default ditetapkan ke 0. Zoom 1 akan menggandakan pembesaran. Zoom dibatasi antara 0 dan tingkat zoom maksimum untuk panorama saat ini. Artinya, nilai apa pun yang berada di luar rentang ini akan ditetapkan ke ekstrem terdekat yang berada dalam rentang tersebut. Misalnya, nilai -1 ditetapkan ke 0. Zoom adalah nilai keempat dari lima nilai yang dipisahkan koma.
    • tilt: menentukan sudut kamera, ke atas atau ke bawah. Rentangnya adalah -90 sampai 0 hingga 90, dengan 90 lurus ke bawah, 0 di tengah horizon, dan -90 lurus ke atas.

Contoh

Berikut beberapa contoh penggunaan intent Street View.

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 angles 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 angles 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)
Piramida di Street View
Gambar 3. Piramida di Street View