Ringkasan

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.
Pilih platform: Android iOS JavaScript

Maps JavaScript API memungkinkan Anda menyesuaikan peta dengan konten dan gambar Anda sendiri untuk ditampilkan di halaman web dan perangkat seluler. Maps JavaScript API menampilkan empat jenis peta dasar (roadmap, satelit, hybrid, dan medan) yang dapat Anda ubah menggunakan lapisan dan gaya, kontrol dan peristiwa, serta berbagai layanan dan library.

Penonton

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

Dokumentasi konseptual ini dirancang untuk memungkinkan Anda secara cepat mulai menjelajahi dan mengembangkan aplikasi dengan Maps JavaScript API. Kami juga memublikasikan Referensi Maps JavaScript API.

Halo, Dunia

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

TypeScript

let map: google.maps.Map;

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

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

let map;

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

window.initMap = initMap;

CSS

/* 
 * 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;
}

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
Lihat contoh

Coba Sampel

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

  1. Kita mendeklarasikan aplikasi sebagai HTML5 menggunakan deklarasi <!DOCTYPE html>.
  2. Kita membuat elemen div bernama "map" untuk menyimpan peta.
  3. Kita menentukan fungsi JavaScript yang membuat peta di div.
  4. Kami memuat Maps JavaScript API menggunakan tag script.

Langkah-langkah ini dijelaskan di bawah.

Mendeklarasikan aplikasi Anda sebagai HTML5

Sebaiknya deklarasikan DOCTYPE benar dalam aplikasi web Anda. Dalam contoh di sini, kami telah mendeklarasikan aplikasi kami sebagai HTML5 menggunakan DOCTYPE HTML5 sederhana seperti yang ditunjukkan di bawah ini:

<!DOCTYPE html>

Sebagian besar browser saat ini akan merender konten yang dideklarasikan dengan DOCTYPE ini dalam "mode standar" yang berarti aplikasi Anda harus lebih sesuai dengan lintas browser. DOCTYPE juga dirancang untuk menurunkan tingkat; browser yang tidak memahaminya akan mengabaikannya, dan menggunakan "mode quirks" untuk menampilkan kontennya.

Perlu diperhatikan bahwa beberapa CSS yang berfungsi dalam mode quirks tidak valid dalam mode standar. Secara khusus, semua ukuran berbasis persentase harus mewarisi elemen blok induk, dan jika salah satu ancestor tersebut gagal menentukan ukuran, maka diasumsikan ukuran tersebut 0 x 0 piksel. Oleh karena itu, kami menyertakan deklarasi <style> berikut:

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

Deklarasi CSS ini menunjukkan bahwa container peta <div> (dengan ID map) harus menempati 100% tinggi dari isi HTML. Perhatikan bahwa kita juga harus mendeklarasikan persentase tersebut secara khusus untuk <body> dan <html>.

Memuat Maps JavaScript API

Maps JavaScript API dimuat menggunakan tag script, yang dapat ditambahkan secara inline di file HTML atau secara dinamis menggunakan file JavaScript terpisah. Sebaiknya Anda meninjau kedua pendekatan tersebut, dan memilih salah satu pendekatan yang paling sesuai dengan struktur kode dalam project Anda.

Pemuatan Sebaris

Untuk memuat Maps JavaScript API secara inline dalam file HTML, tambahkan tag script seperti yang ditunjukkan di bawah.

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

Pemuatan Dinamis

Untuk memuat Maps JavaScript API secara dinamis menggunakan file JavaScript terpisah, lihat contoh di bawah. Pendekatan ini memungkinkan Anda menangani semua kode untuk menangani API dari file .js terpisah, dan setara dengan menambahkan tag skrip secara inline.

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);
      

Pemuatan Dinamis

Paket @googlemaps/js-api-loader tersedia untuk membuat pengalaman pemuatan dinamis yang lebih lancar. Aplikasi ini dapat diinstal melalui NPM dengan hal berikut:

npm install @googlemaps/js-api-loader

Paket ini dapat diimpor ke dalam aplikasi dengan:

import { Loader } from "@googlemaps/js-api-loader"

Loader mengekspos antarmuka Promise dan callback. Berikut ini adalah contoh penggunaan metode Promise default load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

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

Atribut Tag Skrip

Perhatikan pada contoh di atas bahwa beberapa atribut ditetapkan pada tag script, yang direkomendasikan. Berikut adalah penjelasan dari setiap atribut.

  • src: URL tempat Maps JavaScript API dimuat, termasuk semua simbol dan definisi yang Anda perlukan untuk menggunakan Maps JavaScript API. URL dalam contoh ini memiliki dua parameter: key, tempat Anda memberikan kunci API, dan callback, tempat Anda menentukan nama fungsi global yang akan dipanggil setelah Maps JavaScript API dimuat sepenuhnya. Baca selengkapnya tentang parameter URL.
  • async: Meminta browser untuk mendownload dan menjalankan skrip secara asinkron. Ketika dijalankan, skrip akan memanggil fungsi yang ditentukan menggunakan parameter callback.

Library

Saat memuat Maps JavaScript API melalui URL, Anda dapat memilih untuk memuat library tambahan melalui penggunaan parameter URL libraries. Library adalah modul kode yang menyediakan fungsi tambahan ke Maps JavaScript API utama, tetapi tidak dimuat kecuali jika Anda memintanya secara khusus. Untuk informasi selengkapnya, lihat Library di Maps JavaScript API.

Memuat API secara sinkron

Dalam tag script yang memuat Maps JavaScript API, Anda dapat menghilangkan atribut defer dan parameter callback. Hal ini akan menyebabkan pemuatan API diblokir hingga API didownload.

Ini mungkin akan memperlambat pemuatan laman Anda. Namun, hal ini berarti Anda dapat menulis tag skrip berikutnya dengan asumsi bahwa API sudah dimuat.

Elemen DOM Peta

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

Agar peta ditampilkan pada laman web, kita harus memesan tempatnya. Umumnya, kami melakukannya dengan membuat elemen div bernama dan mendapatkan referensi ke elemen ini dalam model objek dokumen (DOM) browser.

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

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 ditetapkan oleh properti zoom, dengan zoom 0 sesuai dengan peta Earth yang diperkecil sepenuhnya, dan tingkat zoom yang lebih besar akan diperbesar pada resolusi yang lebih tinggi.

zoom: 8

Menawarkan peta seluruh Bumi sebagai gambar tunggal akan memerlukan peta yang sangat besar, atau peta kecil dengan resolusi yang sangat rendah. Akibatnya, gambar peta dalam Google Maps dan Maps JavaScript API akan dipecah menjadi peta "ubin" dan "tingkat zoom." Pada tingkat zoom rendah, sekumpulan kecil ubin peta mencakup area yang luas; pada tingkat zoom yang lebih tinggi, ubin memiliki resolusi lebih tinggi dan mencakup area yang lebih kecil. Daftar berikut menampilkan perkiraan tingkat detail yang akan Anda lihat di setiap tingkat zoom:

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

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

Untuk informasi tentang cara Maps JavaScript API memuat ubin berdasarkan tingkat zoom saat ini, lihat panduan untuk koordinat peta dan ubin.

Objek Peta

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

Class JavaScript yang mewakili peta adalah class Map. Objek di kelas ini mendefinisikan sebuah peta pada laman. (Anda dapat membuat lebih dari satu instance class ini; setiap objek akan menentukan peta terpisah pada halaman.) Kita membuat instance baru dari class ini menggunakan operator new JavaScript.

Saat membuat instance peta baru, Anda menetapkan elemen HTML <div> di halaman sebagai penampung untuk peta. Node HTML adalah turunan dari objek document JavaScript, dan kita mendapatkan referensi ke elemen ini melalui metode document.getElementById().

Kode ini menentukan variabel (bernama map) dan menetapkan variabel tersebut ke objek Map baru. Fungsi Map() dikenal sebagai konstruktor dan definisinya ditampilkan di bawah ini:

Konstruktor Deskripsi
Map(mapDiv:Node, opts?:MapOptions ) Membuat peta baru di dalam penampung HTML tertentu — yang biasanya merupakan elemen DIV — menggunakan parameter apa pun (opsional) yang diteruskan.

Pemecahan masalah

Kesalahan Kunci API dan Penagihan

Dalam keadaan tertentu, peta yang lebih gelap, atau 'negatif' gambar Street View, yang diberi watermark dengan teks "hanya untuk tujuan pengembangan", dapat ditampilkan. Perilaku ini biasanya mengindikasikan terjadi masalah pada kunci API atau penagihan. Untuk menggunakan produk Google Maps Platform, penagihan harus diaktifkan di akun Anda, dan semua permintaan harus menyertakan kunci API yang valid. Alur berikut akan membantu Anda memecahkan masalah ini:

Jika kode Anda tidak berfungsi:

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

  • Cari kesalahan ketik. Ingat bahwa JavaScript adalah bahasa yang peka huruf besar/kecil.
  • Periksa dasar-dasarnya - beberapa masalah yang paling umum terjadi saat pembuatan peta awal. Misalnya:
    • Konfirmasikan bahwa Anda telah menentukan 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 penerapan referensi.
  • Gunakan debugger JavaScript untuk membantu mengidentifikasi masalah, seperti yang tersedia di Developer Tools Chrome. Mulailah dengan mencari kesalahan di Konsol JavaScript.
  • Posting pertanyaan ke Stack Overflow. Panduan tentang cara memposting pertanyaan bagus tersedia di halaman Dukungan.