Pengantar
Maps Static API menampilkan gambar (baik 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 di beberapa lokasi pada peta. Anda juga dapat melabeli penanda menggunakan karakter alfanumerik.
Gambar Maps Static API disematkan dalam atribut src
tag <img>
, atau yang setara 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. Referensi ini menyediakan pengantar untuk menggunakan API dan materi referensi tentang parameter yang tersedia.
Sebelum 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 dalam format berikut:
https://maps.googleapis.com/maps/api/staticmap?parameters
Jika situs Anda diakses melalui HTTPS, Anda juga harus memuat image 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 maupun HTTPS, parameter URL tertentu diperlukan, sementara beberapa parameter lainnya bersifat opsional. Sesuai dengan standar dalam URL, semua parameter dipisah menggunakan karakter ampersand (&
). Daftar parameter dan kemungkinan nilainya diuraikan dalam dokumen ini.
Maps Static API menentukan gambar peta menggunakan parameter URL berikut:
Parameter lokasi
center
(diperlukan jika penanda tidak ada) menentukan pusat peta, dengan jarak yang 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
(wajib) menentukan dimensi persegi panjang dari gambar peta. Parameter ini menggunakan string berformat{horizontal_value}x{vertical_value}
. Misalnya,500x400
menentukan peta dengan lebar 500 piksel dan tinggi 400 piksel. Peta yang lebarnya lebih kecil dari 180 piksel akan menampilkan logo Google yang berukuran lebih kecil. Parameter ini dipengaruhi oleh parameterscale
; 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 dariscale=1
dengan tetap mempertahankan area cakupan dan tingkat detail yang sama (dengan kata lain, isi peta tidak berubah). Hal ini berguna saat mengembangkan untuk tampilan resolusi tinggi. Nilai defaultnya adalah1
. Nilai yang diterima adalah1
dan2
. Lihat Nilai Skala untuk informasi selengkapnya.format
(opsional) menentukan format gambar yang dihasilkan. Secara default, Maps Static API akan membuat gambar PNG. Ada beberapa format yang memungkinkan 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 besar. Untuk informasi selengkapnya, lihat Format Gambar.maptype
(opsional) menentukan jenis peta yang akan dibuat. Ada beberapa kemungkinan nilai maptype, termasukroadmap
,satellite
,hybrid
, danterrain
. Untuk informasi selengkapnya, lihat Jenis Peta Maps Static API.language
(opsional) menentukan bahasa yang akan digunakan untuk menampilkan label pada ubin peta. Perhatikan, 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 geo-politik. Menerima kode wilayah yang ditetapkan sebagai nilai ccTLD ('top-level domain') yang berisi dua karakter. Lihat Detail Cakupan Google Maps Platform untuk wilayah yang didukung.
Parameter fitur
map_id
(opsional) menentukan ID untuk peta tertentu. ID Peta mengaitkan peta dengan gaya atau fitur tertentu, dan harus termasuk dalam 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 parametermarkers
yang sama selama penanda tersebut menampilkan gaya yang sama; Anda dapat menambahkan penanda tambahan dengan gaya yang berbeda dengan menambahkan parametermarkers
lainnya. Perhatikan bahwa jika Anda memberikan penanda untuk peta, Anda tidak perlu menentukan parametercenter
danzoom
(biasanya diperlukan). Untuk informasi selengkapnya, lihat Penanda Maps Static API.path
(opsional) menentukan satu jalur dari dua atau beberapa titik yang terhubung untuk ditempatkan pada gambar di lokasi yang ditentukan. Parameter ini mengambil string definisi titik yang dipisahkan dengan karakter pipa (|
), atau polyline yang dienkode menggunakan awalanenc:
dalam deklarasi lokasi jalur. Anda dapat memberikan jalur tambahan dengan menambahkan parameterpath
tambahan. Perhatikan bahwa jika Anda menyediakan jalur untuk peta, Anda tidak perlu menentukan parametercenter
danzoom
(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 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 menggunakan argumenfeature
danelement
yang mengidentifikasi fitur yang akan ditata gayanya, dan sekumpulan operasi gaya yang akan diterapkan ke fitur yang dipilih. Anda dapat menyediakan beberapa gaya dengan menambahkan parameterstyle
tambahan. Untuk informasi selengkapnya, lihat panduan untuk peta bergaya.
Parameter kunci dan tanda tangan
key
(wajib) memungkinkan Anda memantau penggunaan API aplikasi 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 hingga 16384 karakter. Dalam praktiknya, Anda mungkin tidak 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 di peta, baik untuk memfokuskan peta di lokasi yang benar (menggunakan parameter center
) dan/atau untuk menempatkan penanda letak opsional (menggunakan parameter markers
) di lokasi di peta. Maps Static API
menggunakan angka (nilai lintang dan bujur) atau string (alamat)
untuk menentukan lokasi tersebut. Nilai ini mengidentifikasi lokasi
yang 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 didefinisikan menggunakan angka dalam string teks yang dipisahkan koma yang memiliki presisi hingga 6 angka di belakang koma. Misalnya, "40.714728,-73.998672" adalah nilai geocode yang valid. Presisi yang melebihi 6 angka di belakang koma akan diabaikan.
Nilai bujur didasarkan pada jaraknya dari Greenwich, Inggris, tempat
meridian utama. Karena Greenwich terletak di lintang 51,477222, kita dapat memasukkan nilai center
51.477222,0
untuk memusatkan peta di Greenwich:
Nilai garis lintang dan garis bujur harus sesuai dengan lokasi yang valid di
permukaan bumi. Lintang dapat mengambil nilai berapa pun antara -90
dan
90
, sedangkan nilai bujur dapat mengambil nilai apa pun antara
-180
dan 180
. Jika Anda menentukan nilai lintang atau bujur yang tidak valid, permintaan Anda akan ditolak sebagai permintaan yang buruk.
Alamat
Sebagian besar orang tidak menggunakan 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/bujur, Anda dapat menentukan string yang menunjukkan alamat. Google akan melakukan geocoding alamat dan menyediakan layanan Maps Static API dengan nilai garis lintang/bujur untuk digunakan dalam menempatkan penanda atau menentukan lokasi. String harus dienkode URL, sehingga alamat seperti "City Hall, New York, NY" harus dikonversi menjadi "City+Hall,New+York,NY", misalnya.
Perhatikan, alamat dapat mencerminkan lokasi akurat, seperti alamat jalan, polyline seperti rute bernama, 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 alamat dapat di-geocoding, Anda dapat menguji alamat menggunakan Utilitas Geocoding ini.
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
Tingkat zoom
Maps di Google Maps memiliki 'tingkat zoom' bilangan bulat yang menentukan resolusi tampilan saat ini. Tingkat zoom antara 0
(tingkat zoom terendah, ketika seluruh dunia dapat dilihat pada satu peta) dan 21+
(sampai ke jalan-jalan dan setiap bangunan) dimungkinkan dalam tampilan roadmap
default. Garis luar bangunan, jika tersedia, akan muncul pada peta di sekitar 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 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 sebagai gantinya.
Daftar berikut menunjukkan perkiraan tingkat detail yang akan Anda lihat pada 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 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
Ukuran gambar
Parameter size
, bersama dengan center
, menentukan area cakupan peta. Ukuran ini juga menentukan ukuran output peta dalam piksel, jika dikalikan dengan nilai scale
(yang secara default ditetapkan ke 1
).
Tabel ini menunjukkan 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 region 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
Nilai skala
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, perangkat seluler semakin banyak yang menggunakan layar beresolusi tinggi dengan kepadatan piksel di atas 300 ppi, yang akan:
- Mengurangi ukuran gambar 200x200 piksel menjadi hanya 0,7 inci, merender label dan ikon terlalu kecil untuk dibaca; atau
- Menskalakan (zoom) gambar agar lebih mudah dibaca, yang menghasilkan gambar yang kabur atau pecah.
Terlalu kecil | Terlalu kabur |
---|---|
![]() |
![]() |
Saat mengembangkan untuk perangkat seluler, Anda dapat menggunakan parameter scale
API untuk menampilkan gambar peta beresolusi lebih tinggi yang memecahkan masalah di atas. Nilai scale
dikalikan dengan size
untuk menentukan ukuran output gambar yang sebenarnya 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 menentukan skala, tetapi dengan piksel dua kali lebih banyak dalam setiap dimensi. Ini termasuk jalan dan label, agar dapat dibaca pada layar berukuran kecil yang beresolusi tinggi, serta saat diskalakan oleh browser.
150x150 | 150x150&skala=2 |
---|---|
![]() |
![]() |
Gambar tersebut juga akan berperforma baik di browser desktop, saat disisipkan
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. Tampilan ini ditampilkan dengan baik di desktop, tetapi terlalu kecil untuk dibaca di perangkat seluler.
- Permintaan kedua menggandakan ukuran peta. Di desktop, CSS akan menyesuaikannya ke
elemen
img
100x100 yang ditentukan, tetapi jika diperkecil gambar, jalan dan label akan menjadi terlalu kecil. Di perangkat seluler, gambar sudah berukuran 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 memperkecil skalanya dengan sempurna, sehingga tidak dapat dibedakan dengan permintaan asli berukuran 100x100, sedangkan browser seluler diuntungkan dengan resolusi tambahan yang dikembalikan oleh API.
Permintaan gambar | |||
---|---|---|---|
Perangkat | 100x100 |
200x200 |
100x100&scale=2 |
Desktop (dengan height="100px" danwidth="100px" pada tagimg ) |
![]() |
![]() |
![]() |
Resolusi Tinggi (disimulasikan) |
![]() |
![]() |
![]() |
Untuk informasi selengkapnya tentang pengembangan untuk layar seluler dan resolusi tinggi, bacaan berikut direkomendasikan:
- Mendukung Beberapa Layar dalam dokumentasi developer Android.
- Rekomendasi Webkit.org untuk mengembangkan Situs Web DPI Tinggi.
- Mendukung Layar Resolusi Tinggi di Library Developer iOS.
Format gambar
Gambar dapat ditampilkan dalam beberapa format grafis web umum: GIF,
JPEG, dan PNG. Parameter format
mengambil salah satu nilai berikut:
png8
ataupng
(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-progres.
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 gambar. gif
, png8
, dan png32
memberikan kompresi lossless.
Sebagian besar gambar JPEG bersifat progresif, yang berarti gambar tersebut akan memuat gambar yang lebih kasar sebelumnya dan meningkatkan resolusi gambar seiring bertambahnya data yang masuk. Hal ini memungkinkan
gambar dimuat dengan cepat di halaman web dan merupakan penggunaan JPEG yang paling luas
saat ini. Namun, beberapa penggunaan JPEG memerlukan
gambar non-progresif (dasar bawaan). Dalam kasus tersebut, Anda dapat menggunakan format jpg-baseline
, yang tidak progresif.
Jenis peta
Maps Static API membuat peta dalam beberapa format, yang tercantum di bawah:
roadmap
(default) menentukan gambar peta jalan standar, seperti yang biasanya ditampilkan di situs Google Maps. Jika tidak ada nilaimaptype
yang ditentukan, Maps Static API akan menayangkan ubinroadmap
secara default.satellite
menentukan citra satelit.terrain
menentukan gambar peta bantuan 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 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
Peta campuran menggunakan citra satelit dan fitur peta jalan yang menonjol untuk membuat peta kombinasi. Contoh berikut menunjukkan jenis peta satelit dan campuran:
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
Peta bergaya
Sesuaikan presentasi peta Google standar dengan menerapkan gaya Anda sendiri. Lihat panduan untuk peta bergaya.
Penanda
Parameter markers
menentukan satu atau beberapa penanda (pin peta) di satu 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 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 oleh karakter pipa (|
), diikuti
dengan satu atau beberapa lokasi yang juga dipisahkan dengan karakter pipa
(|
).
Karena informasi gaya dan informasi lokasi dibatasi melalui karakter pipa, informasi gaya harus muncul terlebih dahulu dalam deskriptor penanda. Setelah server Maps Static API menemukan lokasi di deskripsi penanda, semua parameter penanda lainnya juga diasumsikan sebagai lokasi.
Gaya penanda
Kumpulan deskripsi gaya penanda adalah serangkaian penetapan nilai yang dipisahkan dengan 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 parametersize
tidak ditetapkan, penanda akan muncul dalam ukuran default (normal).color:
(opsional) menetapkan warna 24 bit (contoh:color=0xFFFFCC
) atau warna yang telah ditetapkan dari{black, brown, green, purple, yellow, blue, gray, orange, red, white}
yang ditetapkan.Perhatikan, transparansi (ditetapkan menggunakan nilai warna heksadesimal 32-bit) tidak didukung dalam penanda, meskipun didukung untuk jalur.
label:
(opsional) menentukan satu karakter alfanumerik huruf besar dari kumpulan {A-Z, 0-9}. (Persyaratan untuk karakter huruf besar baru untuk versi API ini.) Perhatikan bahwa penanda default dan berukuranmid
adalah satu-satunya penanda yang mampu menampilkan parameteralphanumeric-character
. Penandatiny
dansmall
tidak mampu menampilkan karakter alfanumerik.
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 4.096 piksel, asalkan dapat dikurangi menjadi kurang dari 4.096 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 ditetapkan sebagai nilai lintang/bujur atau sebagai alamat. Lokasi ini 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 menentukan lokasi penanda pada peta. Jika lokasi berada di luar peta, penanda tersebut tidak akan muncul dalam 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 diberikan.
(Lihat Pemosisian implisit.)
Contoh deklarasi penanda ditampilkan di sini. Perhatikan, kita menentukan satu kumpulan 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
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 ini:
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
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 penyingkat URL memiliki keuntungan berupa encoding URL secara otomatis.
Anda dapat menetapkan titik tambatan untuk ikon khusus. Titik link menetapkan cara
ikon ditempatkan dalam kaitannya dengan lokasi markers
yang ditentukan. Secara default, titik anchor 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 pada ikon (seperti
10,5
), atau sebagai perataan yang telah ditentukan sebelumnya 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 khusus unik per permintaan. Batasan ini tidak berarti bahwa
Anda hanya dapat membatasi 5 lokasi yang ditandai pada peta. Setiap ikon unik dapat digunakan dengan lebih dari satu lokasi markers
di peta Anda.
Format ikon:
- Gambar ikon mungkin dalam format PNG, JPEG, atau GIF, meskipun disarankan untuk menggunakan PNG.
- Ukuran maksimum ikon maksimal 4096 piksel (64x64 untuk gambar persegi).
Contoh ikon kustom
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 2 membuat ikon kustom yang sama seperti contoh 1, tetapi tidak menetapkan posisi ikon menggunakan anchor, yang mengandalkan anchor default di 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
Jalur Maps Static API
Parameter path
menentukan kumpulan satu atau beberapa lokasi yang terhubung oleh jalur ke overlay pada gambar peta. Parameter path
mengambil kumpulan penetapan nilai (deskripsi jalur) dengan
format berikut:
path=pathStyles|pathLocation1|pathLocation2|...
dll.
Perhatikan bahwa kedua titik jalur dipisahkan satu sama lain menggunakan karakter
pipa (|
). Karena informasi gaya dan informasi
titik dipisahkan melalui karakter pipa, informasi gaya harus muncul
terlebih dahulu dalam deskriptor jalur. Setelah server Maps Static API menemukan
lokasi di deskripsi jalur, semua parameter jalur lainnya juga dianggap sebagai
lokasi.
Gaya jalur
Kumpulan deskripsi gaya jalur adalah serangkaian penetapan nilai
yang dipisahkan oleh 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 parameterweight
yang ditetapkan, jalur akan muncul dengan ketebalan default (5 piksel).color:
(opsional) menentukan warna sebagai nilai heksadesimal 24-bit (contoh:color=0xFFFFCC
) atau nilai heksadesimal 32-bit (contoh:color=0xFFFFCCFF
), atau dari kumpulan{black, brown, green, purple, yellow, blue, gray, orange, red, white}
.Jika nilai heksadesimal 32-bit telah ditetapkan, dua karakter terakhir akan menetapkan nilai transparansi alfa 8-bit. Nilai ini bervariasi antara
00
(sepenuhnya transparan) danFF
(sepenuhnya buram). Perhatikan bahwa transparansi didukung dalam jalur, meskipun tidak didukung untuk penanda.fillcolor:
(opsional) menunjukkan bahwa jalur tersebut menandai bidang poligon dan menentukan warna isian untuk digunakan sebagai overlay dalam area tersebut. Kumpulan lokasi berikut tidak boleh berupa loop "tertutup"; server Maps Static API akan secara otomatis menggabungkan titik pertama dan terakhir. Namun, perhatikan bahwa setiap goresan pada bagian 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 salah, 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 tak berkedip:
path=color:0xff0000ff|weight:5
- Garis putih tebal tak berkedip:
path=color:0xffffffff|weight:10
Gaya jalur ini opsional. Jika menginginkan atribut default, Anda dapat melewatkan penentuan atribut jalur; dalam hal ini, "argumen" pertama deskripsi jalur akan terdiri dari titik pertama yang dideklarasikan (lokasi), bukan titik (lokasi) yang pertama dideklarasikan.
Titik jalur
Untuk menggambar jalur, parameter path
juga harus
diteruskan dua titik atau lebih. Maps Static API kemudian 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 default 50% dari Union Square NY ke Times Square, NY.
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%:
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 mendefinisikan bidang poligon di dalam Manhattan, yang meneruskan serangkaian persimpangan sebagai lokasi:
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 menjadi tak terlihat dan bidang poligonal agar 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 Alaska Highway dari Dawson Creek, BC ke Delta Junction, AK dengan polyline yang dienkode:
https://maps.googleapis.com/maps/api/staticmap
?size=400x400¢er=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
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¢er=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
Tampilan yang Terlihat
Gambar dapat menetapkan area pandang dengan menetapkan lokasi yang terlihat menggunakan
parameter visible
. Parameter visible
memerintahkan 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 region yang terlihat juga.) Menentukan area pandang dengan
cara ini akan menghilangkan 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
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 memberikan parameter markers
, path
, atau
visible
, Anda dapat membiarkan Maps Static API
menentukan pusat dan tingkat zoom yang benar secara implisit, berdasarkan evaluasi
posisi elemen-elemen tersebut.
Jika menyediakan dua elemen atau lebih, Maps Static API akan menentukan pusat dan tingkat zoom yang tepat, dengan menyediakan margin yang cukup 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
Ukuran gambar yang lebih besar
Jika Anda memerlukan gambar dengan ukuran lebih besar dari 640 x 640 piksel (atau piksel 1280 x 1280 dengan nilai skala 2), hubungi tim dukungan dan berikan informasi berikut:
- Kasus penggunaan Anda dan alasan Anda memerlukan gambar berukuran besar.
- 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.
- Screenshot, tiruan, atau contoh cara Anda akan menggunakan gambar berukuran besar.
- Estimasi penggunaan bulanan Anda 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 mengeluarkan error atau peringatan jika terjadi masalah. Anda harus memeriksa peringatan secara khusus jika Anda melihat ada sesuatu yang hilang dari peta. Sebaiknya periksa peringatan sebelum meluncurkan aplikasi baru. Perhatikan bahwa peringatan mungkin tidak langsung terlihat karena muncul di header HTTP. Untuk mengetahui informasi selengkapnya, lihat panduan untuk error dan peringatan.