Sekarang adalah hari jadi Google Maps Platform yang ke-15 - Lihat berita dan pengumuman terbaru

Objek Peta

Maps direpresentasikan dalam API oleh kelas GoogleMap dan MapFragment.

Contoh kode

Repositori ApiDemos di GitHub mencakup contoh yang menunjukkan penggunaan objek GoogleMap dan SupportMapFragment:

Menambahkan peta ke aplikasi Android

Langkah-langkah dasar untuk menambahkan peta:

  1. (Anda hanya perlu melakukan langkah ini sekali.) Ikuti langkah-langkah dalam panduan konfigurasi project untuk mendapatkan API, memperoleh kunci, dan menambahkan atribut yang diperlukan ke manifes Android Anda.
  2. Tambahkan object Fragment ke Activity yang akan menangani peta. Cara termudah untuk melakukannya adalah dengan menambahkan elemen <fragment> ke file tata letak untuk Activity.
  3. Terapkan antarmuka OnMapReadyCallback dan gunakan metode callback onMapReady(GoogleMap) untuk mendapatkan handle ke objek GoogleMap. Objek GoogleMap adalah representasi internal dari peta itu sendiri. Untuk menetapkan opsi tampilan untuk peta, Anda perlu memodifikasi objek GoogleMap.
  4. Panggil getMapAsync() pada fragmen untuk mendaftarkan callback.

Berikut adalah detail selengkapnya tentang setiap langkah.

Menambahkan fragmen

Tambahkan elemen <fragment> ke file tata letak aktivitas untuk menentukan objek Fragment. Dalam elemen ini, tetapkan atribut android:name ke "com.google.android.gms.maps.MapFragment". Tindakan tersebut secara otomatis akan melampirkan MapFragment ke aktivitas.

File tata letak berikut berisi elemen <fragment>:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.gms.maps.MapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Anda juga dapat menambahkan MapFragment ke Activity dalam kode. Caranya, buat instance MapFragment baru, lalu panggil FragmentTransaction.add() untuk menambahkan Fragment ke Activity saat ini

 mMapFragment = MapFragment.newInstance();
 FragmentTransaction fragmentTransaction =
         getFragmentManager().beginTransaction();
 fragmentTransaction.add(R.id.my_container, mMapFragment);
 fragmentTransaction.commit();

Menambahkan kode peta

Untuk menangani peta di dalam aplikasi, Anda harus menerapkan antarmuka OnMapReadyCallback dan menetapkan instance callback pada objek MapFragment atau MapView. Tutorial ini menggunakan MapFragment, karena itulah cara paling umum untuk menambahkan peta ke aplikasi. Langkah pertama adalah menerapkan antarmuka callback:

public class MainActivity extends FragmentActivity
    implements OnMapReadyCallback {
...
}

Dalam metode onCreate() Activity Anda, tetapkan file tata letak sebagai tampilan konten. Misalnya, jika file tata letak memiliki nama main.xml, gunakan kode ini:

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    ...
}

Dapatkan handle ke fragmen dengan memanggil FragmentManager.findFragmentById(), dengan meneruskan ID resource elemen <fragment> Anda. Perhatikan bahwa ID resource R.id.map ditambahkan secara otomatis ke project Android saat membuat file tata letak.

Setelah itu, gunakan getMapAsync() untuk menetapkan callback pada fragmen.

MapFragment mapFragment = (MapFragment) getFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

Gunakan metode callback onMapReady(GoogleMap) untuk mendapatkan handle ke objek GoogleMap. Callback akan dipicu jika peta sudah siap digunakan. Hal ini menyediakan instance non-null dari GoogleMap. Anda dapat menggunakan objek GoogleMap, misalnya, guna menetapkan opsi tampilan untuk peta atau menambahkan penanda.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

Objek peta

Maps SDK for Android memungkinkan Anda menampilkan peta Google dalam aplikasi Android. Peta ini memiliki tampilan yang sama seperti peta yang Anda lihat dalam aplikasi Google Maps for Mobile (GMM), dan API tersebut akan mengekspos banyak fitur yang sama. Dua perbedaan penting antara aplikasi GMM dan peta yang ditampilkan oleh Maps SDK for Android adalah:

  • Ubin peta yang ditampilkan oleh API tersebut tidak berisi konten apa pun yang dipersonalisasi, seperti ikon pintar yang dipersonalisasi.
  • Tidak semua ikon di peta dapat diklik. Misalnya, ikon stasiun transportasi umum tidak dapat diklik. Namun, penanda yang Anda tambahkan ke peta dapat diklik, dan API tersebut memiliki antarmuka callback pemroses untuk berbagai interaksi penanda.

Selain fungsi pemetaan, API tersebut juga mendukung berbagai interaksi yang konsisten dengan model UI Android. Misalnya, Anda dapat menyiapkan interaksi dengan peta dengan menentukan pemroses yang merespons gestur pengguna.

Kelas utama saat menangani objek peta adalah kelas GoogleMap. GoogleMap membuat model objek peta dalam aplikasi Anda. Dalam UI, peta akan direpresentasikan oleh objek MapFragment atau MapView.

GoogleMap menangani operasi berikut secara otomatis:

  • Menghubungkan ke layanan Google Maps.
  • Mendownload ubin peta.
  • Menampilkan ubin pada layar perangkat.
  • Menampilkan berbagai kontrol seperti geser dan zoom.
  • Merespons gestur geser dan zoom dengan memindahkan peta dan memperbesar atau memperkecil.

Selain operasi otomatis ini, Anda dapat mengontrol perilaku peta dengan objek dan metode API. Misalnya, GoogleMap memiliki metode callback yang merespons penekanan tombol dan gestur sentuh pada peta. Anda juga dapat menetapkan ikon penanda pada peta dan menambahkan overlay di atasnya, menggunakan objek yang Anda berikan untuk GoogleMap.

MapFragment

MapFragment, subkelas dari kelas Fragment Android, memungkinkan Anda menempatkan peta dalam fragmen Android. Objek MapFragment berfungsi sebagai penampung untuk peta, dan memberikan akses ke objek GoogleMap.

Berbeda dengan View, Fragment merepresentasikan perilaku atau bagian dari antarmuka pengguna dalam suatu aktivitas. Anda dapat mengombinasikan beberapa fragmen dalam satu aktivitas untuk membuat UI multipanel dan menggunakan kembali fragmen dalam beberapa aktivitas. Lihat dokumentasi Android tentang Fragmen untuk mempelajari lebih lanjut.

MapView

MapView, subkelas dari kelas View Android, memungkinkan Anda menempatkan peta dalam View Android. View merepresentasikan wilayah persegi panjang layar, dan merupakan elemen dasar untuk aplikasi dan widget Android. Mirip dengan MapFragment, MapView berfungsi sebagai penampung untuk peta, dengan mengekspos fungsi peta inti melalui objek GoogleMap.

Saat menggunakan API ini dalam mode interaktif penuh, pengguna MapView kelas harus meneruskan metode siklus proses aktivitas berikut ke metode yang sesuai dalam kelas MapView: onCreate(), onStart(), onResume(), onPause(), onStop(), onDestroy(), onSaveInstanceState(), dan onLowMemory(). Repositori ApiDemos pada GitHub mencakup contoh yang menunjukkan cara meneruskan metode siklus proses aktivitas. Saat menggunakan API ini dalam mode ringan, penerusan peristiwa siklus proses bersifat opsional. Untuk mengetahui detailnya, lihat dokumentasi mode ringan.

Jenis peta

Ada banyak jenis peta yang tersedia dalam Maps SDK for Android. Jenis peta mengatur representasi peta secara keseluruhan. Misalnya, atlas biasanya berisi peta politik yang berfokus untuk menampilkan batas, dan peta jalan yang menampilkan semua jalan untuk kota atau wilayah.

Maps SDK for Android menawarkan empat jenis peta, serta opsi untuk tidak memiliki peta sama sekali:

Normal
Peta jalan umum. Menampilkan jalan, beberapa fitur yang dibuat manusia, dan fitur alami penting, seperti sungai. Label jalan dan fitur juga terlihat.
Hibrid
Data foto satelit dengan tambahan peta jalan. Label jalan dan fitur juga terlihat.
Satelit
Data foto satelit. Label jalan dan fitur tidak terlihat.
Medan
Data topografi. Peta ini menyertakan warna, garis kontur, dan label, serta bayangan perspektif. Beberapa jalan dan label juga terlihat.
Tidak satu pun
Tidak ada ubin. Peta akan dirender sebagai petak kosong dan tidak ada petak yang dimuat.

Mengubah tipe peta

Untuk menetapkan jenis peta, panggil metode setMapType() dari objek GoogleMap, dengan meneruskan salah satu konstanta jenis yang ditentukan dalam GoogleMap. Misalnya, untuk menampilkan peta satelit:

GoogleMap map;
...
// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

Gambar di bawah menunjukkan perbandingan peta normal, hibrid, dan medan untuk lokasi yang sama:

Perbandingan MapType

Peta lantai

Pada tingkat zoom tinggi, peta menampilkan denah lantai untuk tempat dalam ruangan seperti bandara, pusat perbelanjaan, toko retail besar, dan stasiun transportasi umum. Denah lantai ini, yang disebut peta lantai, ditampilkan untuk jenis peta 'normal' dan 'satelit' (GoogleMap.MAP_TYPE_NORMAL dan GoogleMap.MAP_TYPE_SATELLITE). Denah lantai ini akan secara otomatis diaktifkan saat pengguna memperbesarnya, dan memudar saat peta diperkecil.

Pemberitahuan penghentian: Dalam rilis mendatang, peta lantai hanya akan tersedia pada jenis peta normal. Dari rilis mendatang, peta lantai tidak akan didukung pada peta satellite, terrain, atau hybrid. Meskipun dalam ruangan tidak didukung, isIndoorEnabled() akan terus menampilkan nilai yang telah ditetapkan melalui setIndoorEnabled(), seperti yang dilakukannya sekarang. Secara default, setIndoorEnabled adalah true. Catatan rilis akan memberi tahu Anda saat dukungan dalam ruangan tidak tersedia pada jenis peta tersebut.

Contoh peta lantai

Menangani peta lantai di API

Inilah rangkuman fungsi peta lantai pada API:

  • Anda dapat menonaktifkan peta lantai dengan memanggil GoogleMap.setIndoorEnabled(false). Secara default, peta lantai diaktifkan. Peta lantai ditampilkan pada satu per satu peta. Secara default, ini adalah peta pertama yang ditambahkan ke aplikasi Anda. Jika ingin menampilkan peta lantai pada peta yang berbeda, nonaktifkan peta pertama, lalu panggil setIndoorEnabled(true) pada peta kedua.
  • Untuk menonaktifkan alat pilih lantai default (pemilih tingkat), panggil GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). Untuk mengetahui detail selengkapnya, lihat Berinteraksi dengan Peta.
  • Antarmuka di GoogleMap, OnIndoorStateChangeListener, memungkinkan Anda menetapkan pemroses untuk dipanggil jika bangunan baru menjadi fokus, atau lantai baru diaktifkan dalam bangunan. Untuk mengetahui detail selengkapnya, lihat Berinteraksi dengan Peta.
  • GoogleMap.getFocusedBuilding() memberi Anda bangunan yang saat ini menjadi fokus. Anda kemudian dapat menemukan lantai yang saat ini aktif dengan memanggil IndoorBuilding.getActiveLevelIndex(). Lihat dokumentasi referensi untuk melihat semua informasi yang tersedia dalam objek IndoorBuilding dan IndoorLevel.

Penataan gaya peta dasar tidak memengaruhi peta lantai.

Menambahkan denah lantai

Peta lantai (denah lantai) tersedia di lokasi tertentu. Jika data denah lantai tidak tersedia untuk bangunan yang ingin Anda tandai dalam aplikasi, Anda dapat:

  • Menambahkan denah lantai ke Google Maps secara langsung. Tindakan tersebut akan membuat denah lantai Anda tersedia bagi semua pengguna Google Maps.
  • Menampilkan denah lantai sebagai overlay bumi atau overlay ubin di peta Anda. Dengan tindakan ini, hanya pengguna aplikasi Anda yang akan melihat denah lantai Anda.

Lapisan lalu lintas

Anda dapat memberi pengguna kemampuan untuk melihat peta dengan informasi kepadatan lalu lintas yang tumpang-tindih di atasnya. Hal ini memberikan ringkasan visual tentang situasi lalu lintas lokal mereka. Anda dapat mengaktifkan dan menonaktifkan lapisan lalu lintas dengan memanggil metode setTrafficEnabled(), dan Anda dapat menentukan apakah lapisan lalu lintas saat ini aktif dengan memanggil metode isTrafficEnabled(). Contoh berikut menunjukkan bagaimana lapisan lalu lintas mungkin muncul pada peta.

Peta Google yang menampilkan lapisan lalu lintas

Mengonfigurasi status awal

Maps API memungkinkan Anda mengonfigurasi status awal peta agar sesuai dengan kebutuhan aplikasi Anda. Anda dapat menetapkan hal-hal berikut:

  • Posisi kamera, termasuk: lokasi, zoom, penjuru, dan kemiringan. Lihat Kamera dan Tampilan untuk detail selengkapnya tentang pemosisian kamera.
  • Jenis peta.
  • Apakah tombol zoom dan/atau kompas muncul di layar.
  • Gestur yang dapat digunakan pengguna untuk memanipulasi kamera.
  • Apakah mode ringan diaktifkan atau tidak. Peta mode ringan adalah gambar bitmap dari peta yang mendukung subkumpulan fungsi yang disediakan oleh API lengkap.

Anda dapat mengonfigurasi status awal peta melalui XML, jika Anda telah menambahkan peta ke file tata letak aktivitas, atau secara terprogram, jika Anda telah menambahkan peta dengan cara tersebut.

Menggunakan atribut XML

Bagian ini menjelaskan cara menetapkan status awal peta jika Anda telah menambahkan peta ke aplikasi menggunakan file tata letak XML.

Maps API menentukan kumpulan atribut XML kustom untuk MapFragment atau MapView yang dapat Anda gunakan untuk mengonfigurasi status awal peta secara langsung dari file tata letak. Atribut berikut saat ini telah ditentukan:

  • mapType. Atribut ini memungkinkan Anda menetapkan jenis peta yang akan ditampilkan. Nilai yang valid mencakup: none, normal, hybrid, satellite, dan terrain.
  • cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt. Atribut ini memungkinkan Anda menetapkan posisi awal kamera. Lihat di sini untuk detail selengkapnya tentang Posisi Kamera dan propertinya.
  • uiZoomControls, uiCompass. Atribut ini memungkinkan Anda menentukan apakah Anda ingin kontrol zoom dan kompas muncul di peta. Lihat UiSettings untuk mengetahui detail selengkapnya.
  • uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures. Atribut ini memungkinkan Anda menentukan gestur mana yang diaktifkan/dinonaktifkan untuk interaksi dengan peta. Lihat UiSettings untuk mengetahui detail selengkapnya.
  • zOrderOnTop. Mengontrol apakah permukaan tampilan peta ditempatkan di bagian atas jendelanya. Lihat SurfaceView.setZOrderOnTop(boolean) untuk mengetahui detail selengkapnya. Perhatikan bahwa tindakan ini akan membuat semua tampilan lain yang dapat muncul di peta (mis., kontrol zoom, tombol Lokasiku) tertutupi.
  • useViewLifecycle. Hanya berlaku jika digunakan bersama MapFragment. Atribut ini menentukan apakah siklus proses peta harus terkait dengan tampilan fragmen atau fragmen itu sendiri. Lihat di sini untuk mengetahui detail selengkapnya.
  • liteMode. Nilai true menetapkan peta ke mode ringan. Peta mode ringan adalah gambar bitmap dari peta yang mendukung subkumpulan fungsi yang disediakan oleh API lengkap. Nilai default atribut ini adalah false.

Untuk menggunakan atribut kustom ini dalam file tata letak XML, Anda harus menambahkan deklarasi ruang nama berikut terlebih dahulu. Anda dapat memilih ruang nama apa pun, tidak harus map:

xmlns:map="http://schemas.android.com/apk/res-auto"

Anda kemudian dapat menambahkan atribut dengan awalan map: ke dalam komponen tata letak, seperti pada atribut Android standar.

Cuplikan kode XML berikut menunjukkan cara mengonfigurasi MapFragment dengan beberapa opsi kustom. Atribut yang sama juga dapat diterapkan ke MapView.

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:map="http://schemas.android.com/apk/res-auto"
  android:name="com.google.android.gms.maps.SupportMapFragment"
  android:id="@+id/map"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

Secara terprogram

Bagian ini menjelaskan cara menetapkan status awal peta jika Anda telah menambahkan peta ke aplikasi secara terprogram.

Jika Anda telah menambahkan MapFragment (atau MapView) secara terprogram, Anda dapat mengonfigurasi status awal dengan meneruskan objek GoogleMapOptions bersama opsi yang ditetapkan. Opsi yang tersedia bagi Anda sama persis dengan opsi yang tersedia melalui XML. Anda dapat membuat objek GoogleMapOptions seperti ini:

GoogleMapOptions options = new GoogleMapOptions();

Kemudian konfigurasikan sebagai berikut:

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

Untuk menerapkan opsi ini saat Anda membuat peta, lakukan salah satu hal berikut:

Padding peta

Video ini menampilkan contoh padding peta.

Peta Google didesain untuk mengisi seluruh wilayah yang ditentukan oleh elemen penampungnya, biasanya MapView atau MapFragment. Beberapa aspek tampilan dan perilaku peta ditentukan oleh dimensi penampungnya:

  • Target kamera akan mencerminkan pusat wilayah dengan padding.
  • Kontrol peta diposisikan sesuai dengan tepi peta.
  • Informasi hukum, seperti pernyataan hak cipta atau logo Google muncul di sepanjang tepi bawah peta.

Anda dapat menambahkan padding di sekitar tepi peta menggunakan GoogleMap.Metode setPadding(). Peta akan terus mengisi seluruh penampung, tetapi posisi teks dan kontrol, gestur peta, dan gerakan kamera akan berperilaku seolah-olah ditempatkan di ruang yang lebih kecil. Hal ini menghasilkan perubahan berikut:

  • Gerakan kamera melalui panggilan API atau penekanan tombol (mis., kompas, tombol Lokasiku, tombol zoom) akan sesuai dengan wilayah dengan padding.
  • getCameraPosition() akan menampilkan bagian pusat wilayah dengan padding.
  • Projection.getVisibleRegion() akan menampilkan wilayah dengan padding.
  • Kontrol UI akan di-offset dari tepi penampung dengan jumlah piksel yang ditetapkan.

Padding dapat berguna saat mendesain UI yang tumpang-tindih di beberapa bagian peta. Misalnya, dalam gambar di bawah, peta diberi padding di sepanjang tepi atas dan kanan. Kontrol peta yang terlihat dan teks hukum akan ditampilkan sepanjang tepi wilayah dengan padding, yang ditampilkan dengan warna hijau, sementara peta akan terus mengisi seluruh penampung, yang ditampilkan dengan warna biru. Dalam contoh ini, Anda dapat mengambangkan menu di atas sisi kanan peta tanpa mengaburkan kontrol peta.

Padding Peta

Melokalkan peta Anda

Jika Anda menambahkan MapView atau MapFragment ke aplikasi, elemen teks pada peta ditampilkan dalam bahasa yang sesuai berdasarkan setelan dan lokasi perangkat pengguna. Anda dapat membatasi bahasa yang digunakan oleh aplikasi ke subkumpulan dari semua bahasa yang didukung, dengan menambahkan item resConfigs ke file Gradle. Hal ini berguna untuk menghapus bahasa yang tidak digunakan, dan juga mengurangi ukuran biner aplikasi Anda. Contoh:

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

Baca selengkapnya tentang melokalkan aplikasi Android Anda.