Cara Menambahkan Peta Interaktif ke Website Anda | Tutorial

Setiap dasbor logistik, daftar real estat, dan aplikasi pengiriman makanan memiliki satu kesamaan: sebuah peta. Jika website Anda belum memilikinya, Anda membiarkan konteks tertinggal. Konteks yang membantu pengguna memahami lokasi, kedekatan, dan hubungan spasial dalam sekejap.

Tutorial ini memandu Anda menambahkan peta yang sepenuhnya interaktif ke proyek JavaScript apa pun. Anda akan mulai dengan peta yang dirender, menambahkan penanda dan popup, menghubungkan pencarian alamat dengan API Geocoding, dan selesai dengan komponen React yang siap produksi yang cocok rapi di Next.js.

Berikut yang akan Anda bangun di akhir:

• Peta vektor langsung yang diautentikasi dengan kunci API Anda
• Penanda yang dapat diklik dengan konten popup khusus
• Fungsi pencarian alamat yang didukung geocoding
• Komponen React yang dapat digunakan kembali dengan pembersihan yang tepat dan penanganan SSR Next.js
• Daftar periksa pengoptimalan kinerja untuk produksi

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Kunci API MapAtlas (daftar gratis, tidak memerlukan kartu kredit). Kunci tunggal ini mengautentikasi setiap layanan MapAtlas: ubin, geocoding, dan routing.
• Proyek JavaScript. HTML biasa, React, Vue, atau Svelte semuanya berfungsi.
• Node.js 18+ jika Anda memasang melalui npm.

Langkah 1: Instal SDK MapAtlas

Tarik SDK ke proyek Anda dengan npm:

npm install @mapmetrics/mapmetrics-gl

Jika Anda bekerja dengan halaman HTML biasa, masukkan tautan CDN ke <head> Anda:

<link rel="stylesheet" href="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css" />
<script src="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js"></script>

Jangan lewatkan impor CSS. Tanpanya, kontrol peta dan popup dirender tanpa gaya. Berfungsi, tetapi rusak secara visual.

Langkah 2: Buat Wadah Peta

SDK mengisi elemen apa pun yang Anda tunjukkan, jadi Anda memerlukan <div> dengan tinggi eksplisit. Ini adalah kesalahan pengaturan paling umum: jika wadah memiliki height: 0, peta diinisialisasi tetapi tetap tidak terlihat.

<div id="map" style="width: 100%; height: 500px;"></div>

Nilai piksel tetap atau unit viewport (100vh, 50vh) keduanya berfungsi. Tinggi persentase hanya berfungsi jika elemen induk juga memiliki tinggi yang ditentukan.

Langkah 3: Render Peta Interaktif Pertama Anda

Tiga baris konfigurasi adalah semua yang diperlukan: wadah, URL gaya dengan kunci API Anda, dan posisi awal.

import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=YOUR_API_KEY',
  center: [4.9041, 52.3676],
  zoom: 12,
});

Buka halaman dan Anda akan melihat peta vektor yang dapat Anda seret, gulir, dan cubit untuk menavigasi. Ubin dimuat sesuai permintaan dari server MapAtlas, jadi tidak ada unduhan berat di awal.

Memilih Gaya Peta

Gaya peta disimpan di akun Anda. Di portal MapMetrics, buka Styles, buat atau sesuaikan gaya, simpan, lalu salin Style URL-nya. URL tersebut sudah membawa token Anda, jadi bisa langsung dimasukkan ke opsi style. Simpan satu gaya untuk setiap tampilan yang Anda butuhkan, misalnya gaya terang untuk aplikasi umum dan gaya gelap untuk dashboard, lalu beralih di antaranya dengan map.setStyle().

Kemenangan cepat: Gunakan gaya gelap untuk panel admin dan alat yang digunakan di lingkungan cahaya rendah. Banyak pengguna lebih menyukainya di ruangan redup, dan gaya ini membuat lapisan data seperti heatmap dan jalur rute menonjol secara visual terhadap latar belakang.

Langkah 4: Tambahkan Penanda dan Popup ke Peta Anda

Peta tanpa penanda hanya sekadar gambar latar belakang. Penanda mengubah tampilan statis menjadi sesuatu yang dapat berinteraksi dengan pengguna.

Penanda Tunggal dengan Popup

const popup = new mapmetricsgl.Popup().setHTML(`
  <strong>Amsterdam Central</strong>
  <p>Stationsplein, 1012 AB Amsterdam</p>
`);

new mapmetricsgl.Marker({ color: '#97C70A' })
  .setLngLat([4.9001, 52.3791])
  .setPopup(popup)
  .addTo(map);

Klik penanda dan popup terbuka. Anda dapat memasukkan HTML apa pun di dalamnya: alamat, thumbnail, tombol CTA, apa pun yang diperlukan UI Anda.

Memplot Beberapa Penanda dari Data

Sebagian besar aplikasi dunia nyata memerlukan lebih dari satu pin. Loop melalui array dan buat penanda untuk setiap entri:

const locations = [
  { name: 'Amsterdam', coords: [4.9041, 52.3676] },
  { name: 'Rotterdam', coords: [4.4777, 51.9244] },
  { name: 'Utrecht',   coords: [5.1214, 52.0907] },
];

locations.forEach(({ name, coords }) => {
  const popup = new mapmetricsgl.Popup().setHTML(`<strong>${name}</strong>`);
  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat(coords)
    .setPopup(popup)
    .addTo(map);
});

Catatan kinerja: Penanda HTML adalah elemen DOM, jadi beberapa ratus penanda saja akan memperlambat peta pada tampilan yang diperkecil. Pada titik itu, pindahkan titik-titiknya ke sumber GeoJSON dengan pengelompokan (didukung langsung oleh SDK) dan gambar sebagai layer. Periksa dokumentasi SDK untuk konfigurasi pengelompokan.

Langkah 5: Tambahkan Pencarian Alamat dengan API Geocoding

API Geocoding mengubah kueri teks (alamat jalan, nama kota, atau landmark) menjadi koordinat yang dapat Anda luncurkan, tandai, atau masukkan ke permintaan routing.

async function searchAddress(query) {
  const url = new URL('https://gateway.mapmetrics-atlas.net/forward-geocode/');
  url.searchParams.set('text', query);
  url.searchParams.set('token', 'YOUR_API_KEY');
  const res  = await fetch(url);
  const data = await res.json();
  if (!data.features.length) return;
  const [lng, lat] = data.features[0].geometry.coordinates;
  const label      = data.features[0].properties.label;
  map.flyTo({ center: [lng, lat], zoom: 14 });
  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat([lng, lat])
    .setPopup(new mapmetricsgl.Popup().setHTML(`<strong>${label}</strong>`))
    .addTo(map);
}
searchAddress('Rijksmuseum, Amsterdam');

Hasil kembali sebagai fitur GeoJSON, jadi mereka terhubung langsung ke lapisan apa pun yang kompatibel dengan GeoJSON, tabel data, atau panggilan API hilir.

Bangun bilah pencarian langsung dalam waktu kurang dari 30 baris: Lampirkan searchAddress ke peristiwa input dari bidang teks, debounce selama 300ms, dan Anda memiliki pencarian peta gaya autocomplete tanpa ketergantungan tambahan.

Mengintegrasikan Peta Interaktif dengan React

Komponen Peta yang Dapat Digunakan Kembali

Bungkus inisialisasi peta dalam useEffect agar berjalan setelah DOM dipasang, dan kembalikan fungsi pembersihan untuk mencegah kebocoran memori saat unmount:

import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

export function MapAtlasMap({ apiKey, center = [4.9041, 52.3676], zoom = 12 }) {
  const containerRef = useRef(null);
  useEffect(() => {
    const map = new mapmetricsgl.Map({
      container: containerRef.current,
      style: `https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=${apiKey}`,
      center, zoom,
    });
    return () => map.remove();
  }, [apiKey]);
  return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}

Gunakan di mana saja dalam pohon komponen Anda:

<MapAtlasMap apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY} center={[4.9041, 52.3676]} zoom={13} />

Menangani Rendering Sisi Server Next.js

SDK peta bergantung pada API browser (window, document) yang tidak ada selama SSR. Impor komponen secara dinamis dengan SSR dinonaktifkan:

import dynamic from 'next/dynamic';
const MapAtlasMap = dynamic(
  () => import('./MapAtlasMap').then(m => m.MapAtlasMap),
  { ssr: false, loading: () => (<div style={{ height: 500, background: '#f0f1f3', borderRadius: 12 }} />) }
);

Placeholder loading menjaga tata letak Anda tetap stabil saat bundel peta diunduh, mencegah cumulative layout shift (CLS), yang penting untuk pengalaman pengguna dan Core Web Vitals.

Daftar Periksa Kinerja Produksi

Sebelum diluncurkan, jalankan pengoptimalan ini:

• Peta lazy-load di bawah lipatan. Gunakan IntersectionObserver untuk menginisialisasi peta hanya saat wadahnya bergulir ke dalam tampilan. Ini menunda sekitar 250 KB JavaScript terkompresi dari pemuatan halaman awal.
• Tahan dengan ubin vektor. Ubin vektor skala dengan bersih ke kepadatan layar apa pun, membutuhkan lebih sedikit permintaan saat pengguna melakukan zoom, dan dapat diberi gaya ulang sisi klien tanpa permintaan server tambahan. MapAtlas melayani ubin vektor secara default.
• Kelompokkan set penanda besar. Beberapa ratus penanda HTML pada tampilan yang diperkecil menyebabkan penurunan frame yang terlihat. Layer GeoJSON yang dikelompokkan menghindari masalah ini.
• Batasi kunci browser. Kunci yang dipakai di browser, termasuk yang ada di variabel lingkungan NEXT_PUBLIC_, bisa dilihat siapa pun yang membuka DevTools. Jangan pernah melakukan commit kunci ke repositori publik, batasi kunci browser ke domain Anda sendiri di portal, dan proxy permintaan melalui backend Anda untuk operasi sensitif.
• Atur maxBounds untuk aplikasi regional. Jika pengguna Anda hanya peduli dengan satu geografi, batasi viewport sehingga ubin di luar area itu tidak pernah diminta. Lebih sedikit panggilan jaringan, pemuatan lebih cepat.

Apa yang Akan Dibangun Selanjutnya

Anda memiliki peta yang dirender, menampilkan penanda, mencari alamat, dan terintegrasi dengan React. Inilah tempat untuk melanjutkan:

• Routing API: Minta petunjuk belokan demi belokan antara dua koordinat. Mengembalikan polyline rute, jarak total, dan waktu tempuh yang diperkirakan.
• Isochrone API: Hasilkan poligon yang mencakup setiap titik yang dapat dicapai dalam n menit. Digunakan untuk zona pengiriman, peta cakupan layanan, dan analisis area tangkapan.
• Matrix API: Hitung waktu tempuh dan jarak antara beberapa asal dan tujuan dalam satu permintaan. Penting untuk pengiriman armada dan optimasi logistik.

Referensi SDK lengkap, dokumentasi gaya, dan panduan API tersedia di docs.mapatlas.xyz.

Pertanyaan Umum

Bisakah saya menambahkan peta interaktif ke website saya secara gratis?

Ya. MapAtlas menawarkan tingkat gratis tanpa kartu kredit yang diperlukan saat pendaftaran. Ini mencakup rendering ubin vektor, API Geocoding, dan API Routing. Itu cukup untuk pengembangan dan penggunaan produksi skala kecil.

Bagaimana cara menyematkan peta di aplikasi React atau Next.js?

Bungkus inisialisasi peta dalam hook useEffect agar berjalan setelah DOM dipasang. Di Next.js, gunakan dynamic() dengan ssr: false untuk menghindari kesalahan rendering sisi server. Kedua pendekatan tercakup dengan contoh copy-paste dalam tutorial ini.

Apa itu ubin vektor, dan mengapa saya harus menggunakannya di atas raster?

Ubin vektor menggambarkan fitur peta (jalan, bangunan, label) sebagai geometri matematis daripada gambar piksel pra-render. Mereka skala tajam ke resolusi apa pun, butuh lebih sedikit unduhan saat Anda melakukan zoom, dan dapat diberi gaya ulang sepenuhnya di klien tanpa putaran server tambahan.

Berapa banyak penanda yang dapat saya tambahkan sebelum kinerja menurun?

Rendering biasanya menurun begitu jumlah penanda HTML mencapai beberapa ratus pada tingkat zoom rendah. Perbaikannya adalah pengelompokan: SDK MapAtlas mendukung pengelompokan sumber GeoJSON secara native, mengelompokkan penanda terdekat pada zoom rendah dan memperluas saat pengguna zoom masuk.

Apakah saya memerlukan pengalaman GIS untuk menggunakan MapAtlas?

Tidak. SDK dirancang untuk pengembang web, bukan spesialis GIS. Anda menginisialisasi peta dengan koordinat dan tingkat zoom, menambahkan penanda dengan pasangan bujur/lintang, dan memanggil API Geocoding dengan teks biasa. Tidak ada database spasial atau peralatan GIS yang diperlukan.