Menambahkan Peta Google dengan Penanda menggunakan JavaScript

Pengantar

Tutorial ini menunjukkan cara menambahkan peta Google dengan penanda ke halaman web menggunakan HTML, CSS, dan JavaScript. Bagian ini juga menunjukkan cara menetapkan opsi peta, dan cara menggunakan penempatan kontrol untuk menambahkan label ke peta.

Berikut adalah peta yang akan Anda buat menggunakan tutorial ini. Penanda diposisikan di Uluru (juga dikenal sebagai Ayers Rock) di Taman Nasional Uluru-Kata Tjuta.

Memulai

Ada tiga langkah untuk membuat peta Google beserta penanda di halaman web Anda:

  1. Mendapatkan kunci API
  2. Membuat halaman HTML
  3. Menambahkan peta beserta penanda

Anda membutuhkan browser web. Pilih salah satu browser yang sudah terkenal seperti Google Chrome (direkomendasikan), Firefox, Safari, atau Edge, berdasarkan platform Anda dari daftar browser yang didukung.

Langkah 1: Dapatkan kunci API

Bagian ini menjelaskan cara mengautentikasi aplikasi ke Maps JavaScript API menggunakan kunci API Anda sendiri.

Ikuti langkah-langkah ini untuk mendapatkan kunci API:

  1. Buka Konsol Google Cloud.

  2. Buat atau pilih project.

  3. Klik Continue untuk mengaktifkan API dan layanan terkait.

  4. Pada halaman Credentials, dapatkan API key (dan tetapkan pembatasan kunci API). Catatan: Jika Anda memiliki kunci API yang tidak dibatasi, atau kunci dengan pembatasan browser, Anda boleh menggunakan kunci tersebut.

  5. Untuk mencegah pencurian kuota dan mengamankan kunci API Anda, lihat Menggunakan Kunci API.

  6. Aktifkan penagihan. Lihat Penggunaan dan Penagihan untuk informasi selengkapnya.

  7. Setelah Anda mendapatkan kunci API, tambahkan kunci tersebut ke cuplikan berikut dengan mengklik "YOUR_API_KEY". Salin dan tempelkan tag skrip bootloader untuk digunakan di halaman web Anda sendiri.

    <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",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Langkah 2: Buat halaman HTML

Berikut adalah kode untuk halaman web HTML dasar:

<!DOCTYPE html>
<!--
 @license
 Copyright 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

<html>
  <head>
    <title>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

Ini adalah halaman HTML yang sangat mendasar yang menggunakan elemen gmp-map untuk menampilkan peta di halaman. Peta akan kosong karena kita belum menambahkan kode JavaScript apa pun.

Memahami kode

Pada tahap ini dalam contoh, kita memiliki:

  • Mendeklarasikan aplikasi sebagai HTML5 menggunakan deklarasi !DOCTYPE html.
  • Memuat Maps JavaScript API menggunakan loader bootstrap.
  • Membuat elemen gmp-map untuk menyimpan peta.

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 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 lebih 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 bahwa beberapa CSS yang bekerja dalam quirks mode tidak valid dalam mode standar. Secara khusus, semua ukuran berbasis persentase harus mewarisi ukurannya dari elemen blok induk, dan jika ada pendahulunya yang gagal menetapkan ukuran, maka ukurannya dianggap 0x0 piksel. Oleh karena itu, kami menyertakan deklarasi style berikut:

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

Memuat Maps JavaScript API

Loader bootstrap menyiapkan Maps JavaScript API untuk dimuat (tidak ada library yang dimuat hingga importLibrary() dipanggil).

<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",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Lihat Langkah 3: Mendapatkan kunci API untuk petunjuk cara mendapatkan kunci API Anda.

Pada tahap tutorial ini, jendela kosong akan muncul, hanya menampilkan teks label yang tidak diformat. Hal ini karena kita belum menambahkan kode JavaScript apa pun.

Buat elemen gmp-map

Agar peta ditampilkan pada halaman web, kita harus menentukan tempat untuk menampilkannya. Biasanya, kami melakukannya dengan membuat elemen gmp-map dan mendapatkan referensi ke elemen ini dalam document object model (DOM) browser. Anda juga dapat menggunakan elemen div untuk melakukannya (pelajari lebih lanjut), tetapi sebaiknya gunakan elemen gmp-map.

Kode di bawah menentukan elemen gmp-map, dan menetapkan parameter center, zoom, dan map-id.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

Opsi center dan zoom selalu diperlukan. Dalam kode di atas, properti center memberi tahu API tempat untuk memusatkan peta, dan properti zoom menentukan tingkat zoom untuk peta. Zoom: 0 adalah zoom terendah, dan menampilkan seluruh Bumi. Tetapkan nilai zoom lebih tinggi untuk memperbesar tampilan Bumi dengan resolusi yang lebih tinggi.

Tingkat zoom

Menampilkan peta seluruh Bumi sebagai gambar tunggal akan memerlukan peta yang sangat besar, atau peta kecil dengan resolusi sangat rendah. Akibatnya, gambar peta dalam Google Maps dan Maps JavaScript API 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 atau benua
  • 10: Kota
  • 15: Jalan
  • 20: Bangunan

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

Kode di bawah ini menjelaskan CSS yang menetapkan ukuran elemen gmp-map.

/* Set the size of the gmp-map element that contains the map */
gmp-map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

Dalam kode di atas, elemen style menetapkan ukuran gmp-map. Tetapkan lebar dan tinggi ke nilai di atas 0 piksel agar peta dapat terlihat. Dalam hal ini, gmp-map ditetapkan ke tinggi 400 piksel dan lebar 100% untuk ditampilkan di seluruh lebar halaman web. Sebaiknya selalu tetapkan gaya tinggi dan lebar secara eksplisit.

Penempatan kontrol

Anda dapat menggunakan penempatan kontrol untuk menambahkan kontrol formulir HTML ke peta. Slot adalah posisi yang telah ditentukan sebelumnya di peta; gunakan atribut slot untuk menetapkan posisi yang diperlukan untuk elemen, dan susun elemen dalam elemen gmp-map. Cuplikan berikut menunjukkan cara menambahkan label HTML ke sudut kiri atas peta.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

Langkah 3: Tambahkan kode JavaScript

Bagian ini menunjukkan cara memuat Maps JavaScript API ke dalam halaman web, dan cara menulis JavaScript Anda sendiri yang menggunakan API tersebut untuk menambahkan peta dengan penanda di dalamnya.

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // Get the gmp-map element.
  const mapElement = document.querySelector(
    "gmp-map"
  ) as google.maps.MapElement;

  // Get the inner map.
  const innerMap = mapElement.innerMap;

  // Set map options.
  innerMap.setOptions({
    mapTypeControl: false,
  });

  // Add a marker positioned at the map center (Uluru).
  const marker = new AdvancedMarkerElement({
    map: innerMap,
    position: mapElement.center,
    title: "Uluru/Ayers Rock",
  });
}
initMap();
index.ts

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector("gmp-map");
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Add a marker positioned at the map center (Uluru).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();
index.js

Kode di atas melakukan hal berikut saat initMap() dipanggil:

  • Memuat library maps dan marker.
  • Mendapatkan elemen peta dari DOM.
  • Menetapkan opsi peta tambahan di peta bagian dalam.
  • Menambahkan penanda ke peta.

Mendapatkan objek peta dan menyetel opsi

innerMap merepresentasikan instance class Map. Untuk menyetel opsi peta, dapatkan instance innerMap dari elemen peta dan panggil setOptions. Cuplikan berikut menunjukkan cara mendapatkan instance innerMap dari DOM, lalu memanggil setOptions:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Tunggu hingga peta dimuat

Saat menggunakan elemen gmp-map, peta dimuat secara asinkron. Hal ini dapat menyebabkan kondisi persaingan jika permintaan lain dibuat pada waktu inisialisasi (misalnya, geolokasi atau permintaan detail Tempat). Untuk memastikan kode Anda hanya berjalan setelah peta dimuat sepenuhnya, gunakan handler peristiwa tidak ada aktivitas addListenerOnce dalam fungsi inisialisasi Anda, seperti yang ditunjukkan di sini:

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

Dengan melakukannya, kode Anda hanya akan dijalankan setelah peta dimuat; handler hanya dipicu satu kali selama siklus proses aplikasi.

Kode contoh lengkap

Lihat contoh kode lengkapnya di sini:

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // Get the gmp-map element.
  const mapElement = document.querySelector(
    "gmp-map"
  ) as google.maps.MapElement;

  // Get the inner map.
  const innerMap = mapElement.innerMap;

  // Set map options.
  innerMap.setOptions({
    mapTypeControl: false,
  });

  // Add a marker positioned at the map center (Uluru).
  const marker = new AdvancedMarkerElement({
    map: innerMap,
    position: mapElement.center,
    title: "Uluru/Ayers Rock",
  });
}
initMap();
index.ts

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector("gmp-map");
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Add a marker positioned at the map center (Uluru).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-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>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
  </head>
  <body>
    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
      <div id="controls" slot="control-inline-start-block-start">
        <h3>My Google Maps Demo</h3>
      </div>
    </gmp-map>
  </body>
</html>
index.html

Mencoba Contoh

Pelajari penanda lebih lanjut:

Tips dan pemecahan masalah

  • Pelajari lebih lanjut cara mendapatkan koordinat lintang/bujur, atau mengonversi alamat menjadi koordinat geografis.
  • Anda dapat mengatur opsi seperti gaya dan properti untuk menyesuaikan peta. Untuk informasi selengkapnya tentang menyesuaikan peta, baca panduan untuk menata gaya, dan menggambar di peta.
  • Gunakan Konsol Alat Developer di browser web untuk menguji dan menjalankan kode, membaca laporan error, dan menyelesaikan masalah pada kode.
  • Gunakan pintasan keyboard berikut untuk membuka konsol di Chrome:
    Command+Option+J (di Mac), atau Control+Shift+J (di Windows).

  • Ikuti langkah-langkah di bawah ini untuk mendapatkan koordinat lintang dan bujur untuk lokasi di Google Maps.

    1. Buka Google Maps di browser.
    2. Klik kanan lokasi persis di peta yang Anda perlukan koordinatnya.
    3. Pilih Ada apa di sini? dari menu konteks yang muncul. Peta menampilkan kartu di bagian bawah layar. Temukan koordinat lintang dan bujur di baris terakhir kartu.

  • Anda dapat mengubah alamat menjadi koordinat lintang dan bujur menggunakan layanan Geocoding. Panduan developer memberikan informasi mendetail tentang memulai layanan Geocoding.