Memulai

Pengguna

Dokumentasi ini dimaksudkan untuk orang yang memahami pemograman JavaScript dan konsep pemrograman berorientasi objek. Anda juga harus memahami Google Maps dari sudut pandang pengguna. Banyak tutorial JavaScript tersedia di Web.

Dokumentasi konseptual ini didesain agar Anda bisa secara cepat mempelajari dan mengembangkan aplikasi dengan Google Maps JavaScript API. Kami juga mempublikasikan Referensi Google Maps JavaScript API.

Halo, Dunia

Cara termudah untuk mulai mempelajari tentang Google Maps JavaScript API adalah melihat contoh sederhana. Laman web berikut menampilkan peta yang berpusat di Sydney, New South Wales, Australia:

var map;
function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -34.397, lng: 150.644},
    zoom: 8
  });
}

<div id="map"></div>

/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}

<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap" async defer></script>

<!DOCTYPE html>
<html>
  <head>
    <title>Simple Map</title>
    <meta name="viewport" content="initial-scale=1.0">
    <meta charset="utf-8">
    <style>
      /* Always set the map height explicitly to define the size of the div
       * element that contains the map. */
      #map {
        height: 100%;
      }
      /* Optional: Makes the sample page fill the window. */
      html, body {
        height: 100%;
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      var map;
      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: {lat: -34.397, lng: 150.644},
          zoom: 8
        });
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

Tampilkan contoh (map-simple.html)

Bahkan dalam contoh sederhana ini, ada beberapa hal yang perlu diperhatikan:

Kami mendeklarasikan aplikasi sebagai HTML5 menggunakan deklarasi <!DOCTYPE html>.
Kami membuat elemen div bernama "map" untuk menyimpan Map.
Kami mendefinisikan fungsi JavaScript yang akan membuat peta dalam div.
Kami memuat Maps JavaScript API menggunakan tag script.

Langkah-langkah ini dijelaskan di bawah.

Mendeklarasikan Aplikasi Anda sebagai HTML5

Kami menyarankan agar Anda mendeklarasikan DOCTYPE sesungguhnya dalam aplikasi web. Dalam contoh di sini, kami telah mendeklarasikan aplikasi sebagai HTML5 menggunakan HTML5 DOCTYPE sederhana seperti yang ditampilkan di bawah ini:

<!DOCTYPE html>

Kebanyakan browser saat ini akan merender materi yang dideklarasikan dengan DOCTYPE dalam "mode standar" yang berarti aplikasi Anda harus memenuhi persyaratan lintas browser. DOCTYPE juga didesain untuk menurunkan tingkat secara halus; browser yang tidak memahaminya akan mengabaikannya, dan menggunakan "mode quirks" untuk menampilkan materinya.

Perhatikan, beberapa CSS yang bekerja dalam mode quirks tidak valid dalam mode standar. Secara khusus, semua ukuran berbasis-persentase harus mewarisi dari elemen blok induk, dan jika ada pendahulunya yang gagal menetapkan ukuran, maka dianggap berukuran 0 x 0 piksel. Karena itu, kami menyertakan deklarasi <style> berikut:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Deklarasi CSS ini menunjukkan kontainer peta <div> (dengan id map) harus mengambil 100% dari tinggi bodi HTML. Perhatikan, kita harus secara khusus mendeklarasikan persentase tersebut untuk <body> dan juga <html>.

Memuat Google Maps JavaScript API

Untuk memuat Google Maps JavaScript API, gunakan tag script seperti yang ada dalam contoh berikut:

    <script async defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>

URL yang terdapat dalam tag script adalah lokasi file JavaScript yang memuat semua simbol dan definisi yang Anda butuhkan untuk menggunakan Maps JavaScript API. Tag script ini diperlukan.

Atribut async memungkinkan browser merender bagian selebihnya dari situs web Anda saat Maps JavaScript API dimuat. Bila API sudah siap, ia akan memanggil fungsi yang ditetapkan menggunakan parameter callback.

Parameter key berisi kunci API aplikasi Anda. Lihat Dapatkan Kunci untuk informasi selengkapnya.

Catatan: Pelanggan Google Maps APIs Premium Plan bisa menggunakan kunci API atau ID klien yang valid ketika memuat API. Dapatkan informasi selengkapnya tentang parameter autentikasi untuk pelanggan Premium Plan.

HTTPS atau HTTP

Menurut kami, keamanan di web sangat penting, dan kami menyarankan penggunaan HTTPS bila memungkinkan. Sebagai bagian dari upaya kami untuk membuat web lebih aman, kami telah menyediakan semua Maps JavaScript API melalui HTTPS. Dengan menggunakan enkripsi HTTPS akan membuat situs Anda lebih aman, dan lebih tahan terhadap aksi pengintaian atau perusakan.

Kami sarankan memuat Maps JavaScript API melalui HTTPS menggunakan tag <script> yang disediakan di atas.

Jika diperlukan, Anda bisa memuat Maps JavaScript API melalui HTTP dengan meminta http://maps.googleapis.com/, atau http://maps.google.cn untuk pengguna di Cina.

Pustaka

Saat memuat Maps JavaScript API melalui URL, Anda juga bisa memuat pustaka tambahan melalui penggunaan parameter URL libraries. Pustaka adalah modul kode yang menyediakan fungsionalitas tambahan pada Maps JavaScript API utama namun tidak dimuat kecuali jika Anda memintanya secara khusus. Untuk informasi selengkapnya, lihat Pustaka di Maps JavaScript API.

Memuat API Secara Serempak

Dalam tag script yang memuat Maps JavaScript API, atribut async dan parameter callback boleh dihilangkan. Hal ini akan menyebabkan pemuatan API diblokir hingga API selesai diunduh.

Ini mungkin akan memperlambat pemuatan laman Anda. Namun itu berarti Anda bisa menulis tag script berikutnya dengan anggapan API tersebut sudah dimuat.

Elemen DOM Peta

<div id="map"></div>

Agar peta ditampilkan pada laman web, kita harus memesan tempatnya. Biasanya, kita melakukan hal ini dengan membuat elemen bernama div dan memperoleh referensi ke elemen ini dalam model objek dokumen (DOM) browser.

Dalam contoh di atas, kami menggunakan CSS untuk menyetel ketinggian div peta ke "100%". Ini akan diperluas untuk mengepaskan ukurannya pada perangkat seluler. Anda mungkin perlu menyesuaikan nilai-nilai lebar dan tinggi berdasarkan ukuran layar dan pengisi browser. Perhatikan, div biasanya mengambil lebarnya dari elemen yang dimuatnya, dan div kosong biasanya memiliki ketinggian 0. Karena itu, Anda harus selalu menyetel ketinggian secara eksplisit pada <div>.

Opsi Peta

Ada dua opsi yang diperlukan untuk setiap peta: center dan zoom.

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

Tingkat Zoom

Resolusi awal untuk menampilkan peta disetel oleh properti zoom, dalam hal ini zoom 0 menyatakan peta bumi yang diperkecil maksimum, dan tingkat zoom yang lebih besar akan memperbesar dengan resolusi lebih tinggi. Menetapkan tingkat zoom sebagai integer.

zoom: 8

Menampilkan peta seluruh Bumi sebagai gambar tunggal akan memerlukan peta yang teramat besar, atau peta kecil dengan resolusi sangat rendah. Akibatnya, gambar peta dalam Google Maps dan Maps JavaScript API akan dipecah menjadi "petak" peta dan "tingkat zoom." Pada tingkat zoom rendah, satu rangkaian kecil petak peta mencakup area yang luas; di tingkat zoom yang lebih tinggi, petak memiliki resolusi lebih tinggi dan mencakup area yang lebih kecil. Daftar berikut menunjukkan perkiraan tingkat detail yang Anda harapkan untuk terlihat di setiap tingkat zoom:

1: Dunia
5: Daratan luas/benua
10: Kota
15: Jalan
20: Bangunan

Tiga gambar berikut memperlihatkan Tokyo dari lokasi yang sama pada tingkat zoom 0, 7 dan 18.

Untuk informasi tentang cara Maps JavaScript API memuat petak berdasarkan tingkat zoom saat ini, lihat Koordinat Petak dalam dokumentasi Tipe Peta.

Objek Peta

map = new google.maps.Map(document.getElementById("map"), {...});

Kelas JavaScript yang menyatakan peta adalah kelas Map. Objek di kelas ini mendefinisikan sebuah peta pada laman. (Anda bisa membuat lebih dari satu instance kelas ini — setiap objek akan mendefinisikan peta terpisah pada laman.) Kita membuat sebuah instance baru dari kelas ini menggunakan operator new JavaScript.

Bila membuat instance peta baru, Anda menetapkan elemen HTML <div> di laman sebagai kontainer untuk peta. Simpul HTML adalah anak dari objek document JavaScript, dan kita memperoleh referensi ke elemen ini melalui metode document.getElementById().

Kode ini mendefinisikan variabel (bernama map) dan memberikan variabel itu ke objek Map baru. Fungsi Map() dikenal sebagai konstruktor dan definisinya ditampilkan di bawah ini:

Konstruktor	Keterangan
`Map(mapDiv:Node, opts?:MapOptions )`	Membuat peta baru dalam kontainer HTML yang diberikan - biasanya elemen DIV - menggunakan parameter (opsional) yang diteruskan.

Pemecahan Masalah

Catatan: Parameter sensor tidak lagi diperlukan.

Untuk membantu Anda agar kode peta benar dan berfungsi, Brendan Kenny dan Mano Marks menunjukkan beberapa kesalahan umum dan cara memperbaikinya di video ini.

Jika kode Anda tidak berhasil:

Cari kesalahan ketik. Ingatlah, JavaScript adalah bahasa yang membedakan huruf besar dan kecil.
Periksa dasar-dasarnya - beberapa masalah yang paling umum terjadi saat awal pembuatan peta. Misalnya:
- Konfirmasikan bahwa Anda telah menetapkan properti zoom dan center di opsi peta Anda.
- Pastikan Anda telah mendeklarasikan elemen div tempat peta akan muncul di layar.
- Pastikan elemen div untuk peta memiliki ketinggian. Secara default, elemen div dibuat dengan ketinggian 0, sehingga tidak terlihat.
Lihat contoh kami untuk implementasi referensi.
Gunakan debugger JavaScript untuk membantu mengidentifikasi masalah, seperti yang tersedia dalam Chrome Developer Tools. Mulailah dengan mencari kesalahan di Konsol JavaScript.
Kirimkan pertanyaan ke Stack Overflow. Panduan mengenai cara mengirimkan pertanyaan yang baik tersedia pada laman Dukungan.

Anda sudah siap!

Pengguna

Halo, Dunia

Mendeklarasikan Aplikasi Anda sebagai HTML5

Memuat Google Maps JavaScript API

HTTPS atau HTTP

Pustaka

Memuat API Secara Serempak

Elemen DOM Peta

Opsi Peta

Tingkat Zoom

Objek Peta

Pemecahan Masalah

Kirim masukan tentang...

Anda sudah siap!

Aktifkan Google Maps JavaScript API

Memulai

Pengguna

Halo, Dunia

Mendeklarasikan Aplikasi Anda sebagai HTML5

Memuat Google Maps JavaScript API

HTTPS atau HTTP

Pustaka

Memuat API Secara Serempak

Elemen DOM Peta

Opsi Peta

Tingkat Zoom

Objek Peta

Pemecahan Masalah

Kirim masukan tentang...