Mulai

Pengantar

Maps Static API menampilkan gambar (GIF, PNG, atau JPEG) sebagai respons terhadap permintaan HTTP melalui URL. Untuk setiap permintaan, Anda dapat menentukan lokasi peta, ukuran gambar, tingkat zoom, jenis peta, dan penempatan penanda opsional pada berbagai lokasi pada peta. Anda juga dapat memberi label penanda menggunakan karakter alfanumerik.

Gambar Maps Static API disematkan dalam atribut src tag <img>, atau padanannya dalam bahasa pemrograman lain.

Dokumen ini menjelaskan format URL Maps Static API yang diperlukan dan parameter yang tersedia. Artikel ini juga menunjukkan beberapa tips dan trik dalam menentukan URL Anda.

Sebelum memulai

Dokumen ini ditujukan untuk developer situs dan seluler yang ingin menyertakan gambar Maps Static API dalam halaman web atau aplikasi seluler. Panduan ini menyediakan pengantar tentang penggunaan API dan materi referensi tentang parameter yang tersedia.

Sebelum Anda mulai mengembangkan dengan Maps Static API, tinjau persyaratan autentikasi (Anda memerlukan kunci API) serta informasi penggunaan dan penagihan API (Anda harus mengaktifkan penagihan pada project Anda).

Parameter URL

URL Maps Static API harus dengan bentuk berikut:

https://maps.googleapis.com/maps/api/staticmap?parameters

Jika situs Anda diakses melalui HTTPS, Anda juga harus memuat gambar Maps Static API melalui HTTPS untuk menghindari notifikasi keamanan browser. HTTPS juga direkomendasikan jika permintaan Anda menyertakan informasi pengguna yang sensitif, seperti lokasi pengguna:

https://maps.googleapis.com/maps/api/staticmap?parameters

Baik menggunakan HTTP atau HTTPS, parameter URL tertentu diperlukan sedangkan beberapa parameter lainnya bersifat opsional. Seperti standar dalam URL, semua parameter dipisah menggunakan karakter ampersand (&). Daftar parameter dan kemungkinan nilainya disebutkan dalam dokumen ini.

Penting: Diskusi tentang parameter URL menggunakan contoh yang diberikan dalam bentuk pra-escape agar lebih jelas. Sebelum mengirim permintaan apa pun ke API, parameternya harus dienkode ke URL dengan benar. Misalnya, banyak parameter menggunakan karakter pipa (|) sebagai pemisah, yang harus dienkode sebagai %7C di URL final, seperti dalam contoh singkat di bagian atas dokumen ini. Untuk informasi selengkapnya, lihat Membuat URL yang Valid.

Maps Static API menentukan gambar peta menggunakan parameter URL berikut:

Parameter lokasi

• center (diperlukan jika penanda tidak ada) menentukan pusat peta, yang berjarak sama dari semua tepi peta. Parameter ini mengambil lokasi sebagai pasangan {latitude,longitude} yang dipisahkan koma (misalnya "40.714728,-73.998672") atau alamat string (misalnya "city hall, new york, ny") yang mengidentifikasi lokasi unik di permukaan bumi. Untuk informasi selengkapnya, lihat Lokasi.
• zoom (diperlukan jika penanda tidak ada) menentukan tingkat zoom peta, yang menentukan tingkat pembesaran peta. Parameter ini mengambil nilai numerik yang sesuai dengan tingkat zoom wilayah yang diinginkan. Untuk mengetahui informasi selengkapnya, lihat Tingkat zoom.

Parameter peta

• size (diperlukan) menentukan dimensi persegi panjang gambar peta. Parameter ini menggunakan string berupa {horizontal_value}x{vertical_value}. Misalnya, 500x400 menentukan peta dengan lebar 500 piksel dan tinggi 400 piksel. Maps yang lebarnya lebih kecil dari 180 piksel akan menampilkan logo Google dengan ukuran yang diperkecil. Parameter ini dipengaruhi oleh parameter scale; ukuran output akhir adalah produk dari nilai ukuran dan skala.
• scale (opsional) memengaruhi jumlah piksel yang ditampilkan. scale=2 menampilkan piksel dua kali lebih banyak dari scale=1 dengan tetap mempertahankan area cakupan dan tingkat detail yang sama (dengan kata lain, konten peta tidak berubah). Hal ini berguna saat mengembangkan untuk tampilan resolusi tinggi. Nilai defaultnya adalah 1. Nilai yang diterima adalah 1 dan 2. Lihat Nilai Skala untuk informasi selengkapnya.
• format (opsional) menentukan format gambar yang dihasilkan. Secara default, Maps Static API membuat gambar PNG. Ada beberapa kemungkinan format termasuk jenis GIF, JPEG, dan PNG. Format yang Anda gunakan bergantung pada cara Anda ingin menampilkan gambar. JPEG biasanya memberikan kompresi yang lebih besar, sedangkan GIF dan PNG memberikan detail yang lebih baik. Untuk informasi selengkapnya, lihat Format Gambar.
• maptype (opsional) menentukan jenis peta yang akan dibuat. Ada beberapa nilai maptype yang mungkin, termasuk roadmap, satellite, hybrid, dan terrain. Untuk informasi selengkapnya, lihat Jenis Peta Maps Static API.
• language (opsional) menentukan bahasa yang akan digunakan untuk menampilkan label pada ubin peta. Perhatikan bahwa parameter ini hanya didukung untuk beberapa ubin negara; jika bahasa tertentu yang diminta tidak didukung untuk kumpulan ubin, bahasa default untuk kumpulan ubin tersebut akan digunakan.
• region (opsional) menentukan batas yang sesuai untuk ditampilkan, berdasarkan sensitivitas geopolitik. Menerima kode wilayah yang ditetapkan sebagai nilai dua karakter ccTLD ('top-level domain'). Lihat Detail Cakupan Google Maps Platform untuk wilayah yang didukung.

Parameter fitur

• map_id (opsional) menetapkan ID untuk peta tertentu. ID Peta mengaitkan peta dengan gaya atau fitur tertentu, dan harus merupakan bagian dari project yang sama dengan kunci API yang digunakan untuk menginisialisasi peta. Untuk informasi selengkapnya, lihat Menggunakan ID Peta.
• markers (opsional) menentukan satu atau beberapa penanda untuk dilampirkan ke gambar di lokasi yang ditentukan. Parameter ini menggunakan definisi penanda tunggal dengan parameter yang dipisahkan oleh karakter pipa (|). Beberapa penanda dapat ditempatkan dalam parameter markers yang sama asalkan menunjukkan gaya yang sama; Anda dapat menambahkan penanda tambahan dengan gaya yang berbeda dengan menambahkan parameter markers tambahan. Perhatikan bahwa jika memberikan penanda untuk peta, Anda tidak perlu menentukan parameter center dan zoom (biasanya diperlukan). Untuk informasi selengkapnya, lihat Penanda Maps Static API.
• path (opsional) menentukan satu jalur dari dua atau beberapa titik yang terhubung untuk menempatkan gambar di lokasi yang ditetapkan. Parameter ini mengambil string definisi titik yang dipisahkan karakter pipa (|), atau polyline yang dienkode menggunakan awalan enc: dalam deklarasi lokasi jalur. Anda dapat memberikan jalur tambahan dengan menambahkan parameter path tambahan. Perhatikan bahwa jika Anda memberikan jalur untuk peta, Anda tidak perlu menentukan parameter center dan zoom (biasanya diperlukan). Untuk informasi selengkapnya, lihat Jalur Maps Static API.
• visible (opsional) menentukan satu atau beberapa lokasi yang harus tetap terlihat di peta, meskipun tidak ada penanda atau indikator lain yang akan ditampilkan. Gunakan parameter ini untuk memastikan bahwa fitur atau lokasi peta tertentu ditampilkan di Maps Static API.
• style (opsional) menentukan gaya kustom untuk mengubah tampilan fitur tertentu (jalan, taman, dan fitur lainnya) di peta. Parameter ini menerima argumen feature dan element yang mengidentifikasi fitur yang akan diberi gaya, dan sekumpulan operasi gaya yang akan diterapkan pada fitur yang dipilih. Anda dapat menyediakan beberapa gaya dengan menambahkan parameter style tambahan. Untuk informasi selengkapnya, lihat panduan untuk peta bergaya.

Parameter kunci dan tanda tangan

• key (wajib) memungkinkan Anda memantau penggunaan API aplikasi Anda di Google Cloud Console, dan memastikan Google dapat menghubungi Anda terkait aplikasi Anda jika diperlukan. Untuk informasi selengkapnya, lihat Menggunakan Kunci API dengan Maps Static API.
• signature (direkomendasikan) adalah tanda tangan digital yang digunakan untuk memverifikasi bahwa situs yang membuat permintaan menggunakan kunci API Anda telah diberi otorisasi untuk melakukannya. Permintaan tanpa tanda tangan digital mungkin akan gagal. Untuk informasi selengkapnya, lihat Menggunakan Tanda Tangan Digital.

Pembatasan ukuran URL

URL Maps Static API dibatasi maksimal 16384 karakter. Dalam praktiknya, Anda mungkin tidak akan memerlukan URL yang lebih panjang dari ini, kecuali jika Anda menghasilkan peta yang rumit dengan banyak penanda dan jalur.

Penggunaan Parameter

Maps Static API relatif mudah digunakan, karena hanya terdiri dari URL berparameter. Bagian ini menjelaskan cara menggunakan parameter ini untuk membuat URL Anda.

Menetapkan Lokasi

Maps Static API harus dapat mengidentifikasi lokasi dengan tepat pada peta, baik untuk memfokuskan peta di lokasi yang benar (menggunakan parameter center) dan/atau menempatkan penanda letak opsional (menggunakan parameter markers) di lokasi pada peta. Maps Static API menggunakan angka (nilai lintang dan bujur) atau string (alamat) untuk menentukan lokasi ini. Nilai ini mengidentifikasi lokasi yang telah di-geocoding.

Beberapa parameter (seperti parameter markers dan path) mengambil beberapa lokasi. Dalam kasus tersebut, lokasi dipisahkan dengan karakter pipa (|).

Lintang dan bujur

Lintang dan bujur ditentukan menggunakan angka dalam string teks yang dipisahkan koma yang memiliki presisi hingga 6 tempat desimal. Misalnya, "40.714728,-73.998672" adalah nilai geocode yang valid. Presisi yang melebihi 6 tempat desimal akan diabaikan.

Nilai bujur didasarkan pada jaraknya dari Greenwich, Inggris, yang merupakan lokasi meridian utama. Karena Greenwich terletak di garis lintang 51,477222, kita dapat memasukkan nilai center 51.477222,0 untuk memusatkan peta di Greenwich:

Contoh mungkin tidak tersedia di wilayah Anda.

Nilai lintang dan bujur harus sesuai dengan lokasi yang valid di permukaan bumi. Lintang dapat mengambil nilai apa pun antara -90 dan 90, sedangkan nilai bujur dapat berisi nilai apa pun antara -180 dan 180. Jika Anda menetapkan nilai lintang atau bujur yang tidak valid, permintaan Anda akan ditolak sebagai permintaan yang buruk.

Alamat

Sebagian besar orang tidak menggunakan garis lintang dan bujur; mereka menunjukkan lokasi menggunakan alamat. Proses mengubah alamat menjadi titik geografis dikenal sebagai geocoding dan layanan Maps Static API dapat melakukan geocoding untuk Anda jika Anda memberikan alamat yang valid.

Dalam parameter apa pun yang dapat Anda gunakan untuk memberikan garis lintang/garis bujur, Anda bisa menetapkan string yang menunjukkan alamat. Google akan melakukan geocoding alamat dan memberikan layanan Maps Static API dengan nilai garis lintang/garis bujur untuk digunakan dalam menempatkan penanda atau menentukan lokasi. String ini harus dienkode URL, sehingga alamat seperti "City Hall, New York, NY" harus dikonversi menjadi "City+Hall,New+York,NY", misalnya.

Perhatikan, alamat mungkin mencerminkan lokasi akurat, seperti alamat jalan, polyline seperti rute yang diberi nama, atau bidang poligon seperti kota, negara, atau taman nasional. Untuk hasil polylinear dan poligon, server Maps Static API akan menggunakan titik tengah garis/area sebagai pusat alamat. Jika ragu tentang cara geocoding alamat, Anda dapat menguji alamat menggunakan Utilitas Geocoding ini.

Catatan: Jika Anda memilih untuk menentukan lokasi menggunakan metode yang memerlukan geocoding, seperti string alamat atau polyline yang dapat dibaca manusia, permintaannya dibatasi hingga maksimum 15 lokasi. Batas ini hanya berlaku untuk lokasi yang memerlukan geocoding. Ini tidak berlaku untuk lokasi yang ditentukan dengan koordinat lintang/bujur.

Contoh berikut menghasilkan gambar peta statis untuk Berkeley, CA:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Tingkat zoom

Maps di Google Maps memiliki 'tingkat zoom' bilangan bulat yang menentukan resolusi tampilan saat ini. Tingkat zoom antara 0 (tingkat zoom terendah, saat seluruh dunia dapat dilihat pada satu peta) dan 21+ (hingga ke jalan dan bangunan individual) dapat dilakukan dalam tampilan roadmap default. Garis luar bangunan, jika tersedia, akan muncul pada peta dengan tingkat zoom 17. Nilai ini berbeda dari area ke area dan dapat berubah dari waktu ke waktu seiring perkembangan data.

Google Maps menetapkan tingkat zoom 0 untuk mencakup seluruh bumi. Setiap tingkat zoom berikutnya akan menggandakan presisi baik dalam dimensi horizontal maupun vertikal. Informasi selengkapnya tentang cara melakukannya tersedia di dokumentasi Google Maps JavaScript API.

Catatan: tidak semua tingkat zoom muncul pada semua lokasi di bumi. Tingkat zoom bervariasi tergantung lokasi, karena data di beberapa bagian dunia lebih rinci daripada di lokasi lain.

Jika Anda mengirim permintaan untuk tingkat zoom yang tidak memiliki ubin peta, Maps Static API akan menampilkan gambar kosong.

Daftar berikut menunjukkan perkiraan tingkat detail yang akan Anda lihat di setiap tingkat zoom:

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

Contoh ini meminta dua peta Manhattan dengan nilai center yang sama, tetapi masing-masing berada pada tingkat zoom 12 dan 14:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

  

Contoh mungkin tidak tersedia di wilayah Anda.

Ukuran gambar

Parameter size, bersama dengan center, menentukan area cakupan peta. Atribut ini juga menentukan ukuran output peta dalam piksel, jika dikalikan dengan nilai scale (yaitu 1 secara default).

Tabel ini menampilkan nilai maksimum yang diizinkan untuk parameter size di setiap nilai scale.

scale=1	scale=2
640x640	640x640 (menampilkan 1280x1280 piksel)

Contoh ini meminta "irisan" bumi di khatulistiwa dengan tingkat zoom 1:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh ini meminta peta kecil, berukuran 100 x 100 piksel yang berpusat pada wilayah yang sama. Perhatikan logo Google yang lebih kecil:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Nilai penskalaan

Parameter size pada Maps Static API menentukan ukuran peta dalam piksel, sehingga peta dengan size=200x200 akan ditampilkan sebagai 200 piksel kali 200 piksel. Pada monitor komputer LCD, yang biasanya menampilkan sekitar 100 piksel per inci (ppi), peta 200x200 akan berukuran sekitar 2 inci dalam setiap dimensinya.

Namun, semakin banyak perangkat seluler yang menyertakan layar beresolusi tinggi dengan kepadatan piksel di atas 300 ppi, yang:

• Mengurangi ukuran gambar 200x200 piksel menjadi hanya 0,7 inci, merender label dan ikon menjadi terlalu kecil untuk dibaca; atau
• Menskalakan (zoom) gambar agar lebih mudah dibaca, sehingga menghasilkan gambar yang buram atau pecah.

Terlalu kecil	Terlalu kabur

Saat mengembangkan aplikasi untuk perangkat seluler, Anda dapat menggunakan parameter scale API untuk menampilkan gambar peta beresolusi lebih tinggi yang akan memecahkan masalah di atas. Nilai scale dikalikan dengan size untuk menentukan ukuran output sebenarnya dari gambar dalam piksel, tanpa mengubah area cakupan peta. Nilai scale default adalah 1; nilai yang diterima adalah 1 dan 2.

Misalnya, nilai skala 2 akan menampilkan area cakupan peta yang sama dengan permintaan tanpa skala yang ditentukan, tetapi dengan piksel dua kali lebih banyak dalam setiap dimensi. Ini mencakup jalan dan label, sehingga dapat dibaca pada layar berukuran kecil dan beresolusi tinggi, serta saat diskalakan oleh browser.

150x150	150x150& skala=2

Gambar seperti itu juga akan berperforma baik di browser desktop, jika dimasukkan ke dalam tag img atau div dengan tinggi dan lebar yang disetel menggunakan CSS. Browser akan memperkecil gambar ke ukuran yang tepat, tanpa mengurangi kualitas.

Tabel ini menunjukkan tiga permintaan gambar yang berbeda.

• Yang pertama adalah untuk gambar 100x100, tanpa menetapkan nilai skala. Banner ini ditampilkan dengan baik di desktop, tetapi terlalu kecil untuk dibaca di perangkat seluler.
• Permintaan kedua menggandakan ukuran peta. Pada desktop, CSS menyesuaikannya ke dalam elemen img 100x100 yang ditentukan, tetapi jika diperkecil gambar, jalan dan label akan menjadi terlalu kecil. Pada perangkat seluler, ukuran gambar sudah tepat, tetapi sekali lagi, jalan dan label tidak terbaca.
• Permintaan ketiga adalah untuk peta 100x100 dengan scale=2. Gambar ditampilkan dengan detail 200 piksel; desktop akan menurunkan skalanya dengan sempurna, sehingga tidak dapat dibedakan dengan permintaan asli 100x100, sedangkan browser seluler diuntungkan dengan resolusi tambahan yang dikembalikan oleh API.

Permintaan gambar
Perangkat	100x100	200x200	100x100&scale=2
Desktop (dengan height="100px" dan width="100px" pada tag img)
Resolusi Tinggi (disimulasikan)

Tips: Platform seluler, seperti Android dan iOS, memungkinkan aplikasi mendukung layar resolusi tinggi dengan menentukan gambar terpisah untuk setiap resolusi. Parameter skala memudahkan permintaan gambar peta untuk layar resolusi standar, dan peta yang cocok untuk layar resolusi tinggi, cukup dengan menetapkan scale=1 dan scale=2.

Untuk informasi selengkapnya tentang cara mengembangkan aplikasi untuk ponsel dan tampilan resolusi tinggi, sebaiknya baca informasi berikut:

• Mendukung Beberapa Layar dalam dokumentasi developer Android.
• Rekomendasi Webkit.org untuk mengembangkan Situs Web DPI Tinggi.
• Mendukung Layar Resolusi Tinggi di iOS Developer Library.

Format gambar

Gambar dapat ditampilkan dalam beberapa format grafis web umum: GIF, JPEG, dan PNG. Parameter format menggunakan salah satu nilai berikut:

• png8 atau png (default) menetapkan format PNG 8 bit.
• png32 menentukan format PNG 32 bit.
• gif menentukan format GIF.
• jpg menentukan format kompresi JPEG.
• jpg-baseline menentukan format kompresi JPEG non-progresif.

Contoh berikut meminta peta dalam format gif dan png:

  https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=gif&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
  https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=png&&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

jpg dan jpg-baseline biasanya memberikan ukuran gambar terkecil, meskipun melakukannya melalui kompresi "lossy" yang dapat menurunkan kualitas gambar. gif, png8, dan png32 memberikan kompresi lossless.

Sebagian besar gambar JPEG bersifat progresif, yang berarti gambar tersebut memuat gambar yang lebih kasar sebelumnya dan memperbaiki resolusi gambar saat semakin banyak data yang masuk. Hal ini memungkinkan gambar dimuat dengan cepat di halaman web dan merupakan penggunaan JPEG yang paling umum saat ini. Namun, beberapa penggunaan JPEG memerlukan gambar non-progresif (baseline). Dalam kasus ini, sebaiknya gunakan format jpg-baseline, yang merupakan format non-progresif.

Jenis peta

Maps Static API membuat peta dalam beberapa format, yang tercantum di bawah:

• roadmap (default) menetapkan gambar peta jalan standar, seperti yang biasanya ditampilkan di situs Google Maps. Jika tidak ada nilai maptype yang ditentukan, Maps Static API akan menampilkan ubin roadmap secara default.
• satellite menentukan image satelit.
• terrain menentukan gambar peta relief fisik, yang menampilkan medan dan vegetasi.
• hybrid menentukan campuran dari gambar satelit dan peta jalan, yang menampilkan lapisan transparan dari jalan-jalan utama dan nama tempat pada citra satelit.

Anda dapat melihat perbedaan antara jenis peta jalan dan jenis medan dalam contoh kode ini.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

  

Contoh mungkin tidak tersedia di wilayah Anda.

Peta campuran menggunakan citra satelit dan fitur peta jalan terkemuka untuk membuat peta kombinasi. Contoh berikut menunjukkan jenis peta hibrid dan satelit:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

  

Contoh mungkin tidak tersedia di wilayah Anda.

Peta bergaya

Sesuaikan penyajian peta Google standar dengan menerapkan gaya Anda sendiri. Lihat panduan untuk peta bergaya.

Penanda

Parameter markers menentukan kumpulan satu atau beberapa penanda (pin peta) di kumpulan lokasi. Setiap penanda yang ditentukan dalam satu deklarasi markers harus menunjukkan gaya visual yang sama; jika ingin menampilkan penanda dengan gaya yang berbeda, Anda harus menyediakan beberapa parameter markers dengan informasi gaya yang terpisah.

Parameter markers mengambil kumpulan penetapan nilai (deskripsi penanda) dengan format berikut:

markers=markerStyles|markerLocation1| markerLocation2|... dll.

Kumpulan markerStyles dideklarasikan di awal deklarasi markers dan terdiri dari nol atau beberapa deskriptor gaya yang dipisahkan dengan karakter pipa (|), diikuti dengan satu atau beberapa lokasi yang juga dipisahkan dengan karakter pipa (|).

Karena informasi gaya dan informasi lokasi dibatasi dengan karakter pipa, informasi gaya harus muncul terlebih dahulu di setiap deskriptor penanda. Setelah server Maps Static API menemukan lokasi di deskripsi penanda, semua parameter penanda lainnya juga dianggap sebagai lokasi.

Gaya penanda

Kumpulan deskripsi gaya penanda adalah serangkaian penetapan nilai yang dipisahkan oleh karakter pipa (|). Deskripsi gaya ini menentukan atribut visual yang akan digunakan saat menampilkan penanda dalam deskripsi penanda ini. Deskripsi gaya ini berisi penetapan kunci/nilai berikut:

• size: (opsional) menentukan ukuran penanda dari {tiny, mid, small} yang ditetapkan. Jika tidak ada parameter size yang ditetapkan, penanda akan muncul dalam ukuran default (normal).

• color: (opsional) menentukan warna 24 bit (contoh: color=0xFFFFCC) atau warna yang telah ditentukan dari {black, brown, green, purple, yellow, blue, gray, orange, red, white} yang ditetapkan.

  Perhatikan bahwa transparansi (ditetapkan menggunakan nilai warna heksadesimal 32-bit) tidak didukung dalam penanda, meskipun didukung untuk jalur.

• label: (opsional) menentukan satu karakter alfanumerik uppercase dari kumpulan {A-Z, 0-9}. (Persyaratan untuk karakter huruf besar baru untuk versi API ini.) Perhatikan bahwa penanda default dan berukuran mid adalah satu-satunya penanda yang mampu menampilkan parameter alphanumeric-character. Penanda tiny dan small tidak dapat menampilkan karakter alfanumerik.

Catatan: daripada menggunakan penanda ini, Anda dapat menggunakan ikon kustom Anda sendiri. (Untuk mengetahui informasi selengkapnya, lihat Ikon kustom.)

Penskalaan penanda

Nilai scale dikalikan dengan ukuran gambar penanda untuk menghasilkan ukuran output penanda yang sebenarnya dalam piksel. Nilai skala default adalah 1; nilai yang diterima adalah 1, 2, dan 4.

Batas ukuran piksel pada gambar berlaku setelah penskalaan diterapkan. Misalnya, jika penanda ditetapkan ke scale:2, penanda dapat lebih besar dari ukuran maksimum 4096 piksel, asalkan penanda dikurangi menjadi kurang dari 4096 piksel setelah penskalaan. Gunakan penskalaan penanda bersama dengan penskalaan peta saat menampilkan peta dengan resolusi lebih tinggi.

Lokasi penanda

Setiap deskripsi penanda harus berisi kumpulan satu atau beberapa lokasi yang menentukan lokasi untuk menempatkan penanda pada peta. Lokasi ini dapat ditentukan sebagai nilai lintang/bujur atau sebagai alamat. Lokasi tersebut dipisahkan menggunakan karakter pipa (|).

Catatan: Jika Anda memilih untuk menentukan lokasi penanda menggunakan metode yang memerlukan geocoding, seperti string alamat atau polyline yang dapat dibaca manusia, permintaan dibatasi hingga maksimum 15 penanda. Batas ini hanya berlaku untuk lokasi penanda yang memerlukan geocoding. Ini tidak berlaku untuk lokasi penanda yang ditetapkan dengan koordinat lintang/bujur.

Parameter lokasi mendefinisikan lokasi penanda pada peta. Jika lokasi berada di luar peta, penanda tersebut tidak akan muncul pada gambar yang dibuat asalkan parameter center dan zoom disediakan. Namun, jika parameter ini tidak diberikan, server Maps Static API akan otomatis membuat gambar yang berisi penanda yang disediakan. (Lihat Posisi implisit.)

Contoh deklarasi penanda ditampilkan di sini. Perhatikan, kita menentukan satu set gaya dan tiga lokasi:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Untuk menentukan penanda dengan gaya yang berbeda, kita perlu menyediakan beberapa parameter markers. Kumpulan parameter markers ini menentukan tiga penanda: satu penanda biru berlabel "S" di 62.107733, -145.5419, satu penanda hijau kecil di "Delta Junction, AK", dan satu penanda kuning berukuran sedang berlabel "C" di "Tok, AK". Penanda tersebut ditampilkan dalam contoh berikut:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Ikon khusus

Daripada menggunakan ikon penanda Google, Anda bebas menggunakan ikon kustom Anda sendiri. Ikon kustom ditentukan menggunakan deskripsi icon dalam parameter markers. Contoh:

markers=icon:URLofIcon|markerLocation

Tentukan icon menggunakan URL (yang harus dienkode URL). Anda dapat menggunakan URL yang dibuat oleh layanan penyingkat URL seperti https://goo.gl. Sebagian besar layanan pemendekan URL memiliki keuntungan berupa encoding URL secara otomatis.

Anda dapat menetapkan titik link untuk ikon kustom. Titik link menetapkan cara penempatan ikon dalam kaitannya dengan lokasi markers yang ditetapkan. Secara default, titik link ikon kustom adalah bagian tengah bawah gambar ikon. Anda dapat menentukan titik link yang berbeda menggunakan deskripsi anchor bersama dengan icon Anda. Tetapkan anchor sebagai titik x,y ikon (seperti 10,5), atau sebagai perataan yang telah ditentukan menggunakan salah satu nilai berikut: top, bottom, left, right, center, topleft, topright, bottomleft, atau bottomright. Contoh:

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

Anda dapat menggunakan hingga lima ikon kustom unik per permintaan. Pembatasan ini tidak berarti bahwa Anda hanya dibatasi untuk 5 lokasi yang ditandai di peta. Setiap ikon unik dapat digunakan dengan lebih dari satu lokasi markers di peta Anda.

Format ikon:

• Gambar ikon boleh dalam format PNG, JPEG, atau GIF, meskipun sebaiknya PNG.
• Ukuran ikon maksimal 4096 piksel (64x64 untuk gambar persegi).

Contoh ikon khusus

Contoh 1 membuat ikon kustom dan memosisikan ikon menggunakan anchor.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Contoh 2 membuat ikon kustom yang sama seperti contoh 1, tetapi tidak menetapkan posisi ikon menggunakan anchor, yang mengandalkan anchor default di bagian tengah bawah.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Jalur Maps Static API

Parameter path menentukan kumpulan satu atau beberapa lokasi yang terhubung oleh jalur ke overlay pada gambar peta. Parameter path menggunakan kumpulan penetapan nilai (deskripsi jalur) dengan format berikut:

path=pathStyles|pathLocation1|pathLocation2|... dll.

Perhatikan bahwa kedua titik jalur dipisahkan menggunakan karakter pipa (|). Karena informasi gaya dan informasi titik dipisahkan dengan karakter pipa, informasi gaya harus muncul terlebih dahulu dalam deskriptor jalur mana pun. Setelah server Maps Static API menemukan lokasi di deskriptor jalur, semua parameter jalur lainnya juga diasumsikan sebagai lokasi.

Gaya jalur

Kumpulan deskripsi gaya jalur adalah serangkaian penetapan nilai yang dipisahkan dengan karakter pipa (|). Deskriptor gaya ini menentukan atribut visual yang akan digunakan saat menampilkan jalur. Dekriptor gaya ini berisi penetapan kunci/nilai berikut:

• weight: (opsional) menentukan ketebalan jalur dalam piksel. Jika tidak ada parameter weight yang ditetapkan, jalur akan muncul dengan ketebalan default (5 piksel).

• color: (opsional) menentukan warna sebagai nilai heksadesimal 24-bit (contoh: color=0xFFFFCC) atau heksadesimal 32-bit (contoh: color=0xFFFFCCFF), atau dari kumpulan {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Ketika nilai heksadesimal 32-bit ditentukan, dua karakter terakhir akan menetapkan nilai transparansi alfa 8-bit. Nilai ini bervariasi antara 00 (sepenuhnya transparan) dan FF (sepenuhnya tidak tembus pandang). Perhatikan bahwa transparansi didukung dalam jalur, meskipun tidak didukung untuk penanda.

• fillcolor: (opsional) menunjukkan bahwa jalur tersebut menandai area poligon dan menentukan warna isian untuk digunakan sebagai overlay dalam area tersebut. Kumpulan lokasi berikut tidak perlu berupa loop "tertutup"; server Maps Static API akan otomatis menggabungkan titik pertama dan terakhir. Namun, perhatikan bahwa setiap goresan di luar area bidang tidak akan ditutup kecuali jika Anda secara khusus memberikan lokasi awal dan akhir yang sama.
• geodesic: (opsional) menunjukkan bahwa jalur yang diminta harus ditafsirkan sebagai garis geodesi yang mengikuti kelengkungan bumi. Jika false, jalur akan dirender sebagai garis lurus di ruang layar. Nilai defaultnya adalah false (salah).

Beberapa contoh definisi jalur:

• Garis biru tipis, opasitas 50%: path=color:0x0000ff80|weight:1
• Garis merah solid: path=color:0xff0000ff|weight:5
• Garis putih tebal tak berkedip: path=color:0xffffffff|weight:10

Gaya jalur ini opsional. Jika diinginkan, Anda dapat melewatkan penetapan atribut jalur; dalam hal ini, "argumen" pertama deskripsi jalur akan terdiri dari titik, bukan titik pertama yang dideklarasikan (lokasi).

Titik jalur

Untuk menggambar path, parameter path juga harus meneruskan dua titik atau lebih. Selanjutnya, Maps Static API akan menghubungkan jalur di sepanjang titik tersebut, dalam urutan yang telah ditentukan. Setiap pathPoint ditunjukkan dalam pathDescriptor yang dipisahkan dengan karakter | (pipa).

Contoh berikut menentukan jalur biru dengan opasitas 50% default dari Union Square NY ke Times Square, NY.

Contoh mungkin tidak tersedia di wilayah Anda.

Detail parameter path adalah:

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

Contoh berikut menentukan jalur yang sama, bukan menentukan garis merah solid dengan opasitas 100%:

Contoh mungkin tidak tersedia di wilayah Anda.

Detail parameter path ini adalah:

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

Contoh berikutnya menentukan bidang poligon di Manhattan, yang meneruskan serangkaian persimpangan sebagai lokasi:

Contoh mungkin tidak tersedia di wilayah Anda.

Detail parameter path ini adalah:

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

Perhatikan, kita menyetel jalur itu sendiri agar tidak terlihat dan bidang poligonal untuk memiliki opasitas 15%.

Polyline yang dienkode

Sebagai ganti serangkaian lokasi, Anda dapat mendeklarasikan jalur sebagai polyline yang dienkode dengan menggunakan awalan enc: dalam deklarasi lokasi path.

Contoh berikut menguraikan arah jalan Alaska Highway dari Dawson Creek, BC ke Delta Junction, AK dengan polyline yang dienkode:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Seperti jalur standar, jalur polyline yang dienkode juga dapat mendemarkasi area poligon jika argumen fillcolor diteruskan ke parameter path.

Contoh berikut menggambarkan bidang poligonal untuk Brooklyn, NY:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Tampilan yang Terlihat

Gambar dapat menentukan area pandang dengan menentukan lokasi yang terlihat menggunakan parameter visible. Parameter visible menginstruksikan layanan Maps Static API untuk membuat peta sehingga lokasi yang ada tetap terlihat. (Parameter ini dapat digabungkan dengan penanda atau jalur yang ada untuk menentukan wilayah yang terlihat juga.) Menentukan area pandang dengan cara ini akan meniadakan kebutuhan untuk menetapkan tingkat zoom yang tepat.

Contoh berikutnya meminta peta yang berpusat di Boston, MA yang berisi MIT dan Harvard Square di Cambridge, MA:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Pemosisian implisit pada peta

Biasanya, Anda perlu menentukan parameter URL center dan zoom untuk menentukan lokasi dan tingkat zoom peta yang dihasilkan. Namun, jika Anda menyediakan parameter markers, path, atau visible, Anda dapat membiarkan Maps Static API menentukan pusat dan tingkat zoom yang benar secara implisit, berdasarkan evaluasi posisi elemen tersebut.

Jika menyediakan dua elemen atau lebih, Maps Static API akan menentukan pusat dan tingkat zoom yang tepat, dengan menyediakan margin yang luas untuk elemen yang dimuat. Contoh ini menampilkan peta yang berisi San Francisco, Oakland, dan San Jose, CA:

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Contoh mungkin tidak tersedia di wilayah Anda.

Ukuran gambar yang lebih besar

Jika Anda memerlukan gambar dengan ukuran lebih besar dari 640x640 piksel (atau piksel 1280x1280 dengan nilai skala 2), hubungi tim dukungan dan berikan informasi berikut:

1. Kasus penggunaan Anda dan alasan Anda memerlukan gambar berukuran besar.
2. Baik Anda mempertimbangkan untuk menggunakan API Google Maps Platform lainnya (Maps JavaScript API, Maps Embed API, Maps SDK for Android, maupun Maps SDK for iOS) dan mengapa API tersebut tidak memenuhi kebutuhan Anda.
3. Screenshot, tiruan, atau contoh cara Anda akan menggunakan gambar berukuran besar.
4. Estimasi penggunaan bulanan untuk gambar berukuran besar.

Kami akan meninjau permintaan Anda berdasarkan informasi yang Anda berikan dan menentukan apakah kasus penggunaan Anda mematuhi Persyaratan Layanan Google Maps Platform.

Ukuran maksimum yang dapat kami berikan adalah 2048 x 2048 piksel.

Pemecahan masalah dan dukungan

Untuk informasi selengkapnya tentang penggunaan Maps Static API, lihat halaman dukungan.

Maps Static API mungkin memberikan error atau peringatan jika terjadi masalah. Anda harus memeriksa peringatan secara khusus jika melihat bahwa ada sesuatu yang hilang dari peta. Sebaiknya periksa juga peringatan sebelum meluncurkan aplikasi baru. Perhatikan, peringatan mungkin tidak langsung terlihat karena muncul di header HTTP. Untuk mengetahui informasi selengkapnya, lihat panduan untuk error dan peringatan.