Sematkan peta

Panduan ini menunjukkan cara menyematkan peta interaktif ke halaman web Anda.

Membuat URL Maps Embed API

Berikut adalah contoh URL yang memuat Maps Embed API:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

Ganti:

  • MAP_MODE dengan mode peta Anda.
  • YOUR_API_KEY dengan kunci API Anda. Untuk informasi selengkapnya, lihat Mendapatkan kunci API.
  • PARAMETERS dengan parameter wajib dan opsional untuk mode peta Anda.

Menambahkan URL ke iframe

Untuk menggunakan Maps Embed API di halaman web, tetapkan URL yang telah Anda buat sebagai nilai atribut src iframe. Kontrol ukuran peta dengan atribut height dan width iframe, misalnya:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="strict-origin-when-cross-origin"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

Contoh iframe di atas menggunakan properti tambahan:

  • Properti allowfullscreen untuk mengizinkan bagian peta tertentu ditampilkan dalam layar penuh.
  • Properti frameborder="0" dan style="border:0" untuk menghapus batas iframe standar dari sekitar peta.
  • Properti referrerpolicy="strict-origin-when-cross-origin" memastikan browser mengirimkan domain situs Anda sebagai header Referer ke Google. Hal ini memungkinkan pembatasan kunci API untuk memvalidasi permintaan, sekaligus menjaga kerahasiaan jalur halaman tertentu Anda.

Anda dapat mengubah ukuran iframe agar sesuai dengan struktur dan desain situs Anda sendiri, tetapi kami mendapati bahwa pengunjung biasanya lebih mudah berinteraksi dengan peta yang lebih besar. Perhatikan bahwa peta sematan tidak didukung di bawah ukuran 200 px di salah satu dimensi.

Informasi perujuk dan pembatasan kunci API

Jika situs hosting memiliki tag meta referrer yang ditetapkan ke no-referrer atau same-origin, browser tidak akan mengirim header Referer ke Google. Hal ini dapat menyebabkan pembatasan kunci API Anda menolak permintaan. Agar pembatasan berfungsi dengan baik, tambahkan properti referrerpolicy ke iframe, seperti pada contoh di atas, untuk secara eksplisit mengizinkan header Referer dikirim ke Google.

  • strict-origin-when-cross-origin (Direkomendasikan): Hanya mengirim domain dasar Anda (misalnya, https://example.com/) ke Google. Tindakan ini akan menjaga jalur halaman spesifik Anda tetap pribadi, sekaligus memungkinkan pembatasan kunci API berfungsi.
  • no-referrer-when-downgrade (Lama): Mengirim seluruh URL, termasuk jalur halaman dan parameter kueri tertentu (misalnya, https://example.com/contact?user=123).

Pelajari lebih lanjut header Referrer-Policy.

Memilih mode peta

Anda dapat menentukan salah satu mode peta berikut untuk digunakan di URL permintaan:

  • place: menampilkan pin peta di tempat atau alamat tertentu, seperti tempat terkenal, bisnis, fitur geografis, atau kota.
  • view: menampilkan peta tanpa penanda atau rute.
  • directions: menampilkan jalur antara dua atau beberapa titik yang ditentukan di peta, serta jarak dan waktu perjalanan.
  • streetview: menampilkan tampilan panorama interaktif dari lokasi yang ditentukan.
  • search: menampilkan hasil penelusuran di seluruh wilayah peta yang terlihat.

Mode place

URL berikut menggunakan mode peta place untuk menampilkan penanda peta di Menara Eiffel:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

Anda dapat menggunakan parameter berikut:

Parameter Jenis Deskripsi Nilai yang diterima
q Wajib Menentukan lokasi penanda peta. Nama tempat, alamat, plus code, atau ID tempat yang di-escape URL. Maps Embed API mendukung + dan %20 saat meng-escape spasi. Misalnya, konversikan "City Hall, New York, NY" menjadi City+Hall,New+York,NY, atau Plus Codes "849VCWC8+R9" menjadi 849VCWC8%2BR9.
center Opsional Menentukan pusat tampilan peta. Menerima nilai lintang dan bujur yang dipisahkan koma; misalnya: 37.4218,-122.0840.
zoom Opsional Menetapkan tingkat zoom awal peta. Nilai berkisar dari 0 (seluruh dunia) hingga 21 (bangunan individual). Batas atas dapat bervariasi bergantung pada data peta yang tersedia di lokasi yang dipilih.
maptype Opsional Menentukan jenis ubin peta yang akan dimuat. roadmap (default) atau satellite
language Opsional Menentukan bahasa yang akan digunakan untuk elemen UI dan untuk tampilan label pada ubin peta. Secara default, pengunjung akan melihat peta dalam bahasa mereka sendiri. Parameter ini hanya didukung untuk beberapa petak negara; jika bahasa tertentu yang diminta tidak didukung untuk set petak, bahasa default untuk set petak tersebut akan digunakan.
region Opsional Menentukan batas dan label yang sesuai untuk ditampilkan, berdasarkan sensitivitas geopolitik. Menerima kode wilayah yang ditetapkan sebagai subtag wilayah unicode dua karakter (non-numerik) yang dipetakan ke nilai dua karakter ccTLD ("domain level teratas") yang sudah dikenal. Lihat Detail Cakupan Google Maps Platform untuk wilayah yang didukung.

Mode view

Contoh berikut menggunakan mode view dan parameter maptype opsional untuk menampilkan tampilan satelit peta:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

Anda dapat menggunakan parameter berikut:

Parameter Jenis Deskripsi Nilai yang diterima
center Wajib Menentukan pusat tampilan peta. Menerima nilai lintang dan bujur yang dipisahkan koma; misalnya: 37.4218,-122.0840.
zoom Opsional Menetapkan tingkat zoom awal peta. Nilai berkisar dari 0 (seluruh dunia) hingga 21 (bangunan individual). Batas atas dapat bervariasi bergantung pada data peta yang tersedia di lokasi yang dipilih.
maptype Opsional Menentukan jenis ubin peta yang akan dimuat. roadmap (default) atau satellite
language Opsional Menentukan bahasa yang akan digunakan untuk elemen UI dan untuk tampilan label pada ubin peta. Secara default, pengunjung akan melihat peta dalam bahasa mereka sendiri. Parameter ini hanya didukung untuk beberapa petak negara; jika bahasa tertentu yang diminta tidak didukung untuk set petak, bahasa default untuk set petak tersebut akan digunakan.
region Opsional Menentukan batas dan label yang sesuai untuk ditampilkan, berdasarkan sensitivitas geopolitik. Menerima kode wilayah yang ditetapkan sebagai subtag wilayah unicode dua karakter (non-numerik) yang dipetakan ke nilai dua karakter ccTLD ("domain level teratas") yang sudah dikenal. Lihat Detail Cakupan Google Maps Platform untuk wilayah yang didukung.

Mode directions

Contoh berikut menggunakan mode directions untuk menampilkan jalur antara Oslo dan Telemark, Norwegia, jarak, dan waktu perjalanan dengan menghindari jalan tol dan jalan raya.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

Anda dapat menggunakan parameter berikut:

Parameter Jenis Deskripsi Nilai yang diterima
origin Wajib Menentukan titik awal untuk menampilkan rute. Nama tempat, alamat, plus code, koordinat lintang/bujur, atau ID tempat yang di-escape URL. Maps Embed API mendukung + dan %20 saat meng-escape spasi. Misalnya, konversikan "City Hall, New York, NY" menjadi City+Hall,New+York,NY, atau Plus Codes "849VCWC8+R9" menjadi 849VCWC8%2BR9.
destination Wajib Menentukan endpoint rute. Nama tempat, alamat, plus code, koordinat lintang/bujur, atau ID tempat yang di-escape URL. Maps Embed API mendukung + dan %20 saat meng-escape spasi. Misalnya, konversikan "City Hall, New York, NY" menjadi City+Hall,New+York,NY, atau Plus Codes "849VCWC8+R9" menjadi 849VCWC8%2BR9.
waypoints Opsional Menentukan satu atau beberapa tempat perantara untuk merutekan rute antara tempat asal dan tujuan. Nama tempat, alamat, atau ID tempat. Beberapa titik jalan dapat ditentukan menggunakan karakter pipa (|) untuk memisahkan tempat (misalnya, Berlin,Germany|Paris,France). Anda dapat menentukan hingga 20 titik jalan.
mode Opsional Menentukan metode perjalanan. Jika tidak ada mode yang ditentukan, Maps Embed API akan menampilkan satu atau beberapa mode yang paling relevan untuk rute yang ditentukan. driving, walking (yang lebih memilih jalur pejalan kaki dan trotoar, jika tersedia), bicycling (yang lebih memilih rute menggunakan jalur sepeda dan jalan yang disukai jika tersedia), transit, atau flying.
avoid Opsional Menentukan fitur yang harus dihindari dalam rute. Perhatikan bahwa hal ini tidak menghalangi rute yang menyertakan fitur yang dibatasi; hal ini membiaskan hasil ke rute yang lebih menguntungkan. tolls, ferries, dan/atau highways. Pisahkan beberapa nilai dengan karakter pipa (misalnya, avoid=tolls|highways).
units Opsional Menentukan metode pengukuran, metrik atau imperial, saat menampilkan jarak dalam hasil. Jika units tidak ditentukan, negara origin kueri akan menentukan unit yang akan digunakan. metric atau imperial
center Opsional Menentukan pusat tampilan peta. Menerima nilai lintang dan bujur yang dipisahkan koma; misalnya: 37.4218,-122.0840.
zoom Opsional Menetapkan tingkat zoom awal peta. Nilai berkisar dari 0 (seluruh dunia) hingga 21 (bangunan individual). Batas atas dapat bervariasi bergantung pada data peta yang tersedia di lokasi yang dipilih.
maptype Opsional Menentukan jenis ubin peta yang akan dimuat. roadmap (default) atau satellite
language Opsional Menentukan bahasa yang akan digunakan untuk elemen UI dan untuk tampilan label pada ubin peta. Secara default, pengunjung akan melihat peta dalam bahasa mereka sendiri. Parameter ini hanya didukung untuk beberapa petak negara; jika bahasa tertentu yang diminta tidak didukung untuk set petak, bahasa default untuk set petak tersebut akan digunakan.
region Opsional Menentukan batas dan label yang sesuai untuk ditampilkan, berdasarkan sensitivitas geopolitik. Menerima kode wilayah yang ditetapkan sebagai subtag wilayah unicode dua karakter (non-numerik) yang dipetakan ke nilai dua karakter ccTLD ("domain level teratas") yang sudah dikenal. Lihat Detail Cakupan Google Maps Platform untuk wilayah yang didukung.

Mode streetview

Maps Embed API memungkinkan Anda menampilkan gambar Street View sebagai panorama interaktif dari lokasi yang ditentukan di seluruh area cakupannya. Foto Sphere kontribusi pengguna, dan koleksi spesial Street View juga tersedia.

Setiap panorama Street View memberikan tampilan penuh 360 derajat dari satu lokasi. Gambar berisi tampilan horizontal 360 derajat (satu putaran penuh) dan tampilan vertikal 180 derajat (dari lurus ke atas sampai lurus ke bawah). Mode streetview menyediakan penampil yang merender panorama yang dihasilkan sebagai bola dunia dengan kamera di tengahnya. Anda dapat memanipulasi kamera untuk mengontrol zoom dan orientasi kamera.

Lihat panorama mode streetview berikut:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

Salah satu parameter URL berikut diperlukan:

  • location menerima lintang dan bujur sebagai nilai yang dipisahkan koma (46.414382,10.013988). API menampilkan panorama yang difoto paling dekat dengan lokasi ini. Karena gambar Street View diperbarui secara berkala, dan foto dapat diambil dari posisi yang sedikit berbeda setiap kali, lokasi Anda mungkin akan dipaskan ke panorama yang berbeda saat gambar diperbarui.

  • pano adalah ID panorama tertentu. Jika menentukan pano, Anda juga dapat menentukan location. location hanya digunakan jika API tidak dapat menemukan ID panorama.

Parameter URL berikut ini bersifat opsional:

Parameter Jenis Deskripsi Nilai yang diterima
heading Opsional Menunjukkan arah kompas kamera dalam derajat searah jarum jam dari Utara. Nilai dalam derajat dari -180° hingga 360°
pitch Opsional menentukan sudut, ke atas atau ke bawah, dari kamera. Nilai positif akan mengarahkan kamera ke atas, sedangkan nilai negatif akan mengarahkan kamera ke bawah. Pitch default 0° ditetapkan berdasarkan posisi kamera saat gambar diambil. Karena itu, pitch 0° sering kali, tetapi tidak selalu, horizontal. Misalnya, gambar yang diambil dari atas bukit kemungkinan akan menampilkan pitch default yang tidak horizontal. Nilai dalam derajat dari -90° hingga 90°
fov Opsional menentukan ruang pandang horizontal gambar. Nilai defaultnya adalah 90°. Saat menangani area pandang berukuran tetap, ruang pandang dapat dianggap sebagai tingkat zoom, dengan angka yang lebih kecil menunjukkan tingkat zoom yang lebih tinggi. Nilai dalam derajat, dengan rentang 10° - 100°
center Opsional Menentukan pusat tampilan peta. Menerima nilai lintang dan bujur yang dipisahkan koma; misalnya: 37.4218,-122.0840.
zoom Opsional Menetapkan tingkat zoom awal peta. Nilai berkisar dari 0 (seluruh dunia) hingga 21 (bangunan individual). Batas atas dapat bervariasi bergantung pada data peta yang tersedia di lokasi yang dipilih.
maptype Opsional Menentukan jenis ubin peta yang akan dimuat. roadmap (default) atau satellite
language Opsional Menentukan bahasa yang akan digunakan untuk elemen UI dan untuk tampilan label pada ubin peta. Secara default, pengunjung akan melihat peta dalam bahasa mereka sendiri. Parameter ini hanya didukung untuk beberapa petak negara; jika bahasa tertentu yang diminta tidak didukung untuk set petak, bahasa default untuk set petak tersebut akan digunakan.
region Opsional Menentukan batas dan label yang sesuai untuk ditampilkan, berdasarkan sensitivitas geopolitik. Menerima kode wilayah yang ditetapkan sebagai subtag wilayah unicode dua karakter (non-numerik) yang dipetakan ke nilai dua karakter ccTLD ("domain level teratas") yang sudah dikenal. Lihat Detail Cakupan Google Maps Platform untuk wilayah yang didukung.

Mode search

Mode Search menampilkan hasil penelusuran di seluruh wilayah peta yang terlihat. Sebaiknya tentukan lokasi untuk penelusuran, baik dengan menyertakan lokasi dalam istilah penelusuran (record+stores+in+Seattle) maupun dengan menyertakan parameter center dan zoom untuk membatasi penelusuran.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

Anda dapat menggunakan parameter berikut:

Parameter Jenis Deskripsi Nilai yang diterima
q Wajib Menentukan istilah penelusuran. Dapat menyertakan batasan geografis, seperti in+Seattle atau near+98033.
center Opsional Menentukan pusat tampilan peta. Menerima nilai lintang dan bujur yang dipisahkan koma; misalnya: 37.4218,-122.0840.
zoom Opsional Menetapkan tingkat zoom awal peta. Nilai berkisar dari 0 (seluruh dunia) hingga 21 (bangunan individual). Batas atas dapat bervariasi bergantung pada data peta yang tersedia di lokasi yang dipilih.
maptype Opsional Menentukan jenis ubin peta yang akan dimuat. roadmap (default) atau satellite
language Opsional Menentukan bahasa yang akan digunakan untuk elemen UI dan untuk tampilan label pada ubin peta. Secara default, pengunjung akan melihat peta dalam bahasa mereka sendiri. Parameter ini hanya didukung untuk beberapa petak negara; jika bahasa tertentu yang diminta tidak didukung untuk set petak, bahasa default untuk set petak tersebut akan digunakan.
region Opsional Menentukan batas dan label yang sesuai untuk ditampilkan, berdasarkan sensitivitas geopolitik. Menerima kode wilayah yang ditetapkan sebagai subtag wilayah unicode dua karakter (non-numerik) yang dipetakan ke nilai dua karakter ccTLD ("domain level teratas") yang sudah dikenal. Lihat Detail Cakupan Google Maps Platform untuk wilayah yang didukung.

Parameter ID tempat

Maps Embed API mendukung penggunaan ID tempat, bukan memberikan nama atau alamat tempat. ID tempat adalah cara yang stabil untuk mengidentifikasi tempat secara unik. Untuk mengetahui informasi selengkapnya, lihat dokumentasi Places API (New).

Maps Embed API menerima ID tempat untuk parameter URL berikut:

  • q
  • origin
  • destination
  • waypoints

Untuk menggunakan ID tempat, Anda harus menambahkan awalan place_id: terlebih dahulu. Kode berikut menentukan New York City Hall sebagai tempat asal untuk permintaan rute: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius menetapkan radius yang ditentukan dalam meter, untuk menelusuri panorama, yang dipusatkan pada lintang dan bujur yang diberikan. Nilai yang valid adalah bilangan bulat non-negatif. Nilai defaultnya adalah 50.

  • source membatasi penelusuran Street View ke sumber yang dipilih. Nilai yang valid adalah:

    • default menggunakan sumber default untuk Street View; penelusuran tidak terbatas pada sumber tertentu.
    • outdoor membatasi penelusuran ke koleksi luar ruangan. Koleksi dalam ruangan tidak disertakan dalam hasil penelusuran. Perhatikan bahwa panorama luar ruangan mungkin tidak ada untuk lokasi yang ditentukan. Perhatikan juga bahwa penelusuran hanya menampilkan panorama yang dapat ditentukan apakah berada di dalam atau di luar ruangan. Misalnya, PhotoSphere tidak ditampilkan karena tidak diketahui apakah foto tersebut diambil di dalam atau di luar ruangan.