Ringkasan

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, hibrida, dan medan) yang dapat Anda ubah menggunakan lapisan dan gaya, kontrol dan peristiwa, serta berbagai layanan dan library.

Audiens

Dokumentasi ini didesain untuk orang yang memahami pemrograman JavaScript dan konsep pemrograman berorientasi objek. Anda juga harus memahami 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;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();index.ts

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();index.js

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;
}
style.css

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>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>index.html

Lihat contoh

Mencoba Contoh

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

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 peta.
Kami menentukan fungsi JavaScript yang membuat peta dalam div.
Kami memuat Maps JavaScript API menggunakan loader bootstrap.

Langkah-langkah ini dijelaskan di bawah.

Memuat Maps JavaScript API

Loader bootstrap adalah cara yang direkomendasikan untuk memuat Maps JavaScript API. Loader JS API juga disediakan sebagai alternatif. Sebaiknya Anda meninjau kedua pendekatan tersebut, lalu memilih salah satu pendekatan yang paling sesuai dengan struktur kode dalam project Anda.

Untuk detail selengkapnya, lihat Memuat Maps JavaScript API.

Loader Bootstrap

Muat Maps JavaScript API dengan menambahkan loader bootstrap inline ke kode aplikasi Anda, seperti yang ditunjukkan dalam cuplikan berikut:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

Untuk memuat library saat runtime, gunakan operator await untuk memanggil importLibrary() dari dalam fungsi asinkron, seperti yang ditampilkan di sini:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();index.ts

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();index.js

Paket js-api-loader NPM

Manfaatkan @googlemaps/js-api-loader untuk menggunakan NPM agar dapat memuat Maps JavaScript API. Instal paket melalui NPM menggunakan perintah 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 callback dan Promise. Berikut ini adalah contoh penggunaan metode Promise default load().

TypeScript

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

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

JavaScript

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

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.js

Mendeklarasikan Aplikasi Anda sebagai HTML5

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

<!DOCTYPE html>

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

Perhatikan, beberapa CSS yang bekerja dalam quirks mode 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. 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 penampung peta <div> (dengan ID map) harus menempati 100% dari tinggi bodi HTML. Perhatikan bahwa kami juga harus mendeklarasikan persentase tersebut untuk <body> dan <html> secara khusus.

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 Inline

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 callback dan Promise. Berikut ini adalah contoh penggunaan metode Promise default load().

TypeScript

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

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

JavaScript

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

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.js

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, yang Anda gunakan untuk menentukan nama fungsi global yang akan dipanggil setelah Maps JavaScript API dimuat sepenuhnya. Baca selengkapnya tentang parameter URL.
async: Meminta browser untuk mendownload dan mengeksekusi skrip secara asinkron. Ketika dieksekusi, skrip akan memanggil fungsi yang ditentukan menggunakan parameter callback.

Library

Saat memuat Maps JavaScript API melalui URL, Anda dapat memilih untuk memuat library tambahan menggunakan operator await untuk memanggil importLibrary() dari dalam fungsi asinkron. 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.

Elemen DOM Peta

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

Agar peta ditampilkan pada halaman web, kita harus menentukan tempat untuk menampilkannya. Umumnya, kami melakukannya dengan membuat elemen div bernama dan mendapatkan referensi ke elemen ini dalam document object model (DOM) browser.

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

Opsi Peta

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

map = new 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 Bumi yang diperkecil sepenuhnya, dan tingkat zoom yang lebih besar akan memperbesar dengan resolusi yang lebih tinggi.

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 "ubin" peta dan "tingkat zoom". Pada tingkat zoom rendah, satu rangkaian 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 memperlihatkan Tokyo dari lokasi yang sama 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 Map(document.getElementById("map"), {...});

Class JavaScript yang mewakili peta adalah class Map. Objek di class ini mendefinisikan sebuah peta pada halaman. (Anda bisa membuat lebih dari satu instance class ini — setiap objek akan mendefinisikan 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 referensi ke elemen ini diperoleh 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 — biasanya elemen DIV — menggunakan parameter (opsional) yang diteruskan.

Memecahkan masalah

Error Kunci API dan Penagihan

Pada kondisi tertentu, peta gelap, atau gambar Street View 'negatif', yang diberi watermark dengan teks "hanya untuk tujuan pengembangan", mungkin 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:

Apakah Anda menggunakan kunci API?

Saya tidak yakin. Bagaimana cara memeriksa apakah saya menggunakan kunci API?

Kunci API diteruskan sebagai parameter key pada URL yang digunakan untuk memuat Maps JavaScript API. Berikut adalah beberapa opsi untuk memeriksa apakah Anda menggunakan kunci API:

Gunakan ekstensi Chrome Google Maps Platform API Checker. Ekstensi ini memungkinkan Anda mengetahui apakah situs Anda mengimplementasikan Maps API berlisensi Google dengan benar atau tidak.
Jika Anda menggunakan library atau plugin untuk memuat Maps JavaScript API, periksa setelan library tersebut dan cari opsi kunci API.
Periksa error pada browser Anda. Jika Anda melihat pesan berikut, Anda tidak menggunakan kunci API Anda dengan benar:

Peringatan Google Maps JavaScript API: NoApiKeys
Error Google Maps JavaScript API: MissingKeyMapError

Untuk developer web:

Jika Anda memiliki akses ke kode sumber dari aplikasi Anda, cari tag <script> yang digunakan untuk memuat Maps JavaScript API. Saat memuat Maps JavaScript API, ganti YOUR_API_KEY pada kode di bawah dengan kunci API Anda.
```
  <script async defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
  </script>
```
Periksa traffic jaringan yang dihasilkan oleh situs Anda pada browser. Di Chrome, Anda dapat melihatnya melalui tab Jaringan pada DevTools. Di sini Anda akan melihat permintaan jaringan yang dibuat oleh situs Anda. Permintaan yang dibuat menggunakan Maps JavaScript API akan berada pada jalur maps/api/js. Di sini Anda dapat mengonfirmasi apakah permintaan menggunakan parameter key. Sebaiknya filter traffic jaringan Anda menurut maps/api/js saat membuka tab Network.

Tidak, saya tidak menggunakan kunci API.

Untuk mendapatkan kunci API, klik tombol di bawah ini. Jika Anda tidak melihat penyiapan terpandu, ikuti petunjuk lengkap pada Memulai Google Maps Platform.
Mulai

Ya, saya menggunakan kunci API.

Bagus! Sekarang periksa apakah akun penagihan telah dikaitkan ke project Anda.

Apakah akun penagihan dikaitkan ke project Anda?

Saya tidak yakin. Bagaimana cara memeriksa apakah akun penagihan dikaitkan ke project saya?

Buka halaman Billing di Google Cloud Console dan pilih project tempat kunci API Anda dibuat. Untuk mengonfirmasi bahwa kunci tersebut terkait dengan project:

Buka bagian Credentials, yang dapat diakses melalui sidebar sebelah kiri pada Google Maps Platform > Credentials.
Pastikan bahwa kunci API yang saat ini digunakan di situs Anda telah tercantum. Jika belum, beralihlah ke project lain, lalu periksa kredensial project tersebut.
Jika tidak dapat menemukan project untuk kunci API Anda, kemungkinan Anda telah kehilangan akses ke project tersebut. Minta bantuan orang lain di organisasi Anda. Jika project asli tidak dapat ditemukan, Anda harus:
1. Membuat project baru. Hal ini dapat dilakukan dengan memilih New Project dari daftar project, atau dengan memilih Create Project melalui halaman Resource Manager.
2. Membuat kunci API baru. Hal ini dapat dilakukan di halaman Credentials. Setelah membuka halaman tersebut, klik Create credentials, lalu pilih API key.

Setelah menemukan project Anda di Konsol Cloud, periksa apakah akun penagihan telah dikaitkan dengan membuka bagian Billing pada menu samping kiri.

Tidak, akun penagihan tidak dikaitkan ke project saya.

Buka halaman Enable Billing di Cloud Console dan tambahkan akun penagihan ke project Anda. Untuk informasi tambahan, lihat Memulai Google Maps Platform.

Ya, akun penagihan telah dikaitkan ke project saya.

Bagus! Sekarang pastikan bahwa metode penagihan yang diberikan sudah valid.

Apakah metode penagihan yang diberikan sudah tidak valid (misalnya kartu kredit yang sudah tidak berlaku)?

Anda dapat menambahkan, menghapus, atau memperbarui metode pembayaran di Cloud Console.

Apakah ada kelebihan pada batas harian yang Anda tetapkan sendiri pada API?

Jika Anda telah menetapkan batas harian pada API, yang umumnya dilakukan untuk mencegah peningkatan tak terduga, Anda dapat memperbaiki masalah ini dengan meningkatkan batas harian.

Anda dapat memeriksa batas harian dengan membuka APIs & Services Dashboard di Cloud Console. Setelah membukanya:

Pilih project jika diminta.
Pilih API dari daftar, lalu klik tab Quotas.

Apakah kunci API Anda memiliki batasan alamat IP?

Kunci API dengan pembatasan alamat IP hanya dapat digunakan pada layanan web yang ditujukan untuk penggunaan dari sisi server (seperti Geocoding API dan Web Service API lainnya). Sebagian besar layanan web ini memiliki layanan yang setara pada Maps JavaScript API (misalnya, lihat Layanan Geocoding). Untuk menggunakan layanan sisi klien Maps JavaScript API, Anda harus membuat kunci API terpisah yang dapat diamankan menggunakan pembatasan perujuk HTTP (lihat Mendapatkan, menambahkan, dan membatasi kunci API).

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 dalam video ini.

Cari kesalahan ketik. Ingatlah, JavaScript adalah bahasa yang peka huruf besar dan kecil.
Periksa dasar-dasarnya - beberapa masalah yang paling umum terjadi saat awal pembuatan peta. Misalnya:
- Pastikan 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 dalam Chrome Developer Tools. Mulailah dengan mencari error di konsol JavaScript.
Posting pertanyaan ke Stack Overflow. Panduan tentang cara memposting pertanyaan bagus tersedia di halaman Dukungan.