Pengantar
Dengan menggunakan URL Maps, Anda dapat membuat URL lintas platform yang universal untuk meluncurkan Google Maps dan melakukan penelusuran, mendapatkan rute dan navigasi, serta menampilkan tampilan peta dan gambar panorama. Sintaksis URL sama, terlepas dari platform yang digunakan.
Anda tidak memerlukan kunci Google API untuk menggunakan URL Maps.
Sintaksis lintas platform universal
Sebagai developer aplikasi Android, aplikasi iOS, atau situs, Anda dapat membuat URL umum, yang akan membuka Google Maps dan melakukan tindakan yang diminta, apa pun platform yang digunakan saat peta dibuka.
- Di perangkat Android:
- Jika aplikasi Google Maps untuk Android diinstal dan aktif, URL akan meluncurkan Google Maps di aplikasi Maps dan melakukan tindakan yang diminta.
- Jika aplikasi Google Maps tidak diinstal atau dinonaktifkan, URL akan meluncurkan Google Maps di browser dan melakukan tindakan yang diminta.
- Di perangkat iOS:
- Jika aplikasi Google Maps for iOS diinstal, URL akan meluncurkan Google Maps di aplikasi Maps dan melakukan tindakan yang diminta.
- Jika aplikasi Google Maps tidak diinstal, URL akan meluncurkan Google Maps di browser dan melakukan tindakan yang diminta.
- Di perangkat lain, URL akan meluncurkan Google Maps di browser dan melakukan tindakan yang diminta.
Sebaiknya gunakan URL lintas platform untuk meluncurkan Google Maps dari aplikasi atau situs Anda, karena URL universal ini memungkinkan penanganan permintaan peta secara lebih luas, terlepas dari platform yang digunakan. Untuk fitur yang hanya dapat berfungsi pada platform seluler (misalnya navigasi belokan demi belokan), Anda dapat memilih untuk menggunakan opsi khusus platform untuk Android atau iOS. Lihat dokumentasi berikut:
- Intent Google Maps untuk Android — khususnya untuk meluncurkan aplikasi Google Maps untuk Android
- Skema URL Google Maps untuk iOS — khususnya untuk meluncurkan aplikasi Google Maps for iOS
Meluncurkan Google Maps dan melakukan tindakan tertentu
Untuk meluncurkan Google Maps dan secara opsional menjalankan salah satu fungsi yang didukung, gunakan skema URL dari salah satu bentuk berikut, bergantung pada tindakan yang diminta:
- Penelusuran — luncurkan Google Maps yang menampilkan pin untuk tempat tertentu, atau lakukan penelusuran umum dan luncurkan peta untuk menampilkan hasilnya:
https://www.google.com/maps/search/?api=1¶meters
- Rute
— minta rute dan luncurkan Google Maps dengan hasil:
https://www.google.com/maps/dir/?api=1¶meters
- Menampilkan peta
— luncurkan Google Maps tanpa penanda atau rute:
https://www.google.com/maps/@?api=1&map_action=map¶meters
- Menampilkan panorama Street View
— luncurkan gambar panorama interaktif:
https://www.google.com/maps/@?api=1&map_action=pano¶meters
Penting: Parameter api=1
mengidentifikasi versi
URL Maps yang menjadi target URL ini. Parameter ini diperlukan dalam setiap permintaan. Satu-satunya nilai yang valid adalah 1. Jika api=1
TIDAK ada di URL,
semua parameter akan diabaikan dan aplikasi Google Maps default akan diluncurkan, baik
di browser maupun aplikasi seluler Google Maps, bergantung pada platform yang digunakan
(misalnya, https://www.google.com/maps).
Membuat URL yang valid
Anda harus mengenkode URL dengan benar.
Misalnya, beberapa parameter menggunakan karakter pipa (|
) sebagai pemisah, yang harus Anda enkode sebagai %7C
di URL final. Parameter lain menggunakan nilai yang dipisahkan koma, seperti koordinat lintang/bujur atau Kota, Status. Anda harus mengenkode koma sebagai %2C
. Lakukan enkode ruang dengan
%20
, atau ganti dengan tanda plus (+
).
Selain itu, URL dibatasi hingga 2.048 karakter untuk setiap permintaan. Perhatikan batas ini saat membuat URL.
Tindakan peta
Tindakan peta yang tersedia adalah: menelusuri, rute, menampilkan peta, dan menampilkan panorama Street View. Anda menentukan tindakan di URL permintaan, beserta parameter wajib dan opsional. Sebagaimana standar dalam URL, Anda memisahkan parameter menggunakan karakter ampersand
(&
). Untuk setiap tindakan, daftar parameter dan kemungkinan nilainya dihitung di bagian Parameter Penelusuran.
Telusuri
Tindakan penelusuran menampilkan hasil penelusuran di seluruh wilayah peta yang terlihat. Saat menelusuri tempat tertentu, peta yang dihasilkan akan menempatkan pin di lokasi yang ditentukan dan menampilkan detail tempat yang tersedia.
Membentuk URL Penelusuran
https://www.google.com/maps/search/?api=1¶meters
Parameter
query
(wajib): Menentukan tempat yang akan disorot di peta. Parameter kueri diperlukan untuk semua permintaan penelusuran.- Tentukan lokasi sebagai nama tempat, alamat, atau koordinat lintang/bujur yang dipisahkan koma. String harus
dienkode ke URL, sehingga alamat
seperti "City Hall, New York, NY" harus dikonversi menjadi
City+Hall%2C+New+York%2C+NY
. - Tentukan istilah penelusuran umum sebagai string
berenkode URL, seperti
grocery+stores
ataurestaurants+in+seattle+wa
.
- Tentukan lokasi sebagai nama tempat, alamat, atau koordinat lintang/bujur yang dipisahkan koma. String harus
dienkode ke URL, sehingga alamat
seperti "City Hall, New York, NY" harus dikonversi menjadi
query_place_id
(opsional): ID tempat adalah ID tekstual yang secara unik mengidentifikasi tempat. Untuk tindakansearch
, Anda harus menentukanquery
, tetapi Anda juga dapat menentukanquery_place_id
. Jika Anda menentukan kedua parameter,query
hanya akan digunakan jika Google Maps tidak dapat menemukan ID tempat. Jika Anda mencoba menautkan ke tempat tertentu secara pasti, ID tempat adalah jaminan terbaik bahwa Anda akan menautkannya ke tempat yang tepat. Sebaiknya kirimkan jugaquery_place_id
ketika Anda membuat kueri untuk lokasi tertentu menggunakan koordinat lintang/bujur.
Contoh penelusuran
Penelusuran lokasi
Dalam penelusuran lokasi, Anda menelusuri lokasi tertentu menggunakan nama tempat, alamat, atau koordinat lintang/bujur yang dipisahkan koma, dan peta yang dihasilkan menampilkan pin di lokasi tersebut. Ketiga contoh ini menggambarkan penelusuran untuk lokasi yang sama, CenturyLink Field (stadion olahraga di Seattle, WA), menggunakan nilai lokasi yang berbeda.
Contoh 1: Menelusuri nama tempat "CenturyLink Field" akan menghasilkan peta berikut:
https://www.google.com/maps/search/?api=1&query=centurylink+field
Contoh 2: Menelusuri Kolom CenturyLink menggunakan koordinat lintang/bujur serta hasil ID tempat di peta berikut:
Contoh 3: Menelusuri Kolom CenturyLink menggunakan hanya hasil koordinat lintang/bujur di peta berikut ini. Perhatikan bahwa ada pin dalam peta, tetapi tidak ada informasi tempat tambahan yang disediakan pada peta atau di panel samping:
https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393
Penelusuran kategoris
Dalam penelusuran kategori, Anda meneruskan istilah penelusuran umum, dan Google Maps
akan mencoba menemukan listingan yang cocok dengan kriteria Anda di dekat lokasi yang Anda tentukan.
Jika tidak ada lokasi yang ditentukan, Google Maps akan mencoba menemukan listingan di sekitar lokasi Anda saat ini. Jika Anda memilih untuk menyediakan lokasi untuk penelusuran kategori, sertakan lokasi dalam string penelusuran umum (misalnya, pizza+seattle+wa
).
Dalam contoh ini, penelusuran restoran pizza di Seattle, WA, menghasilkan peta berikut:
https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa
Directions
Tindakan rute menampilkan jalur antara dua titik atau lebih yang ditentukan pada peta, serta jarak dan waktu perjalanan.
Membentuk URL Rute
https://www.google.com/maps/dir/?api=1¶meters
Parameter
origin
: Menentukan titik awal untuk menampilkan rute. Setelan defaultnya adalah lokasi awal yang paling relevan, seperti lokasi perangkat, jika tersedia. Jika tidak ada, peta yang dihasilkan dapat memberikan bentuk kosong sehingga pengguna dapat memasukkan tempat asal. Nilainya dapat berupa nama tempat, alamat, atau koordinat lintang/bujur yang dipisahkan koma. String harus dienkode ke URL, sehingga alamat seperti "City Hall, New York, NY" harus dikonversi menjadiCity+Hall%2C+New+York%2C+NY
.Catatan: Parameter ini bersifat opsional, kecuali jika Anda menentukan
origin_place_id
di URL Anda. Jika memilih untuk menentukanorigin_place_id
, Anda juga harus menyertakanorigin
dalam URL.origin_place_id
(opsional): ID tempat adalah ID tekstual yang secara unik mengidentifikasi tempat. Jika Anda mencoba menentukan tempat usaha secara pasti, menggunakan ID tempat adalah jaminan terbaik bahwa Anda akan menautkan ke tempat yang tepat. URL yang menggunakan parameter ini juga harus menyertakanorigin
.destination
: Menentukan endpoint rute. Jika tidak ada, peta yang dihasilkan dapat memberikan formulir kosong sehingga pengguna dapat memasukkan tujuan. Nilainya dapat berupa nama tempat, alamat, atau koordinat lintang/bujur yang dipisahkan koma. String harus dienkode ke URL, sehingga alamat seperti "City Hall, New York, NY" harus dikonversi menjadiCity+Hall%2C+New+York%2C+NY
.Catatan: Parameter ini bersifat opsional, kecuali jika Anda menentukan
destination_place_id
di URL Anda. Jika memilih untuk menentukandestination_place_id
, Anda juga harus menyertakandestination
dalam URL.destination_place_id
(opsional): ID tempat adalah ID tekstual yang secara unik mengidentifikasi tempat. Jika Anda mencoba menentukan tempat usaha secara pasti, menggunakan ID tempat adalah jaminan terbaik bahwa Anda akan menautkan ke tempat yang tepat. URL yang menggunakan parameter ini juga harus menyertakandestination
.travelmode
(opsional): Menentukan metode perjalanan. Opsinya adalahdriving
,walking
(yang lebih memilih jalur pejalan kaki dan trotoar, jika tersedia),bicycling
(yang merutekan melalui jalur sepeda dan jalan yang disukai jika tersedia), atautransit
. Jikatravelmode
tidak ditentukan, Google Maps akan menampilkan satu atau beberapa moda yang paling relevan untuk rute yang ditentukan dan/atau preferensi pengguna.dir_action=navigate
(opsional): Meluncurkan navigasi belokan demi belokan atau pratinjau rute ke tujuan yang ditentukan, berdasarkan apakah tempat asal tersedia atau tidak. Jika pengguna menentukan tempat asal dan tidak dekat dengan lokasi pengguna saat ini, atau lokasi perangkat saat ini tidak tersedia, peta akan meluncurkan pratinjau rute. Jika pengguna tidak menentukan origin (dalam hal ini, origin ditetapkan secara default ke lokasi perangkat saat ini), atau tempat asal dekat dengan lokasi pengguna saat ini, peta akan meluncurkan navigasi belokan demi belokan. Perhatikan bahwa navigasi tidak tersedia di semua produk Google Maps dan/atau di antara semua tujuan; dalam kasus tersebut, parameter ini akan diabaikan.waypoints
: Menentukan satu atau beberapa tempat perantara untuk merutekan rute melalui antaraorigin
dandestination
. Beberapa titik jalan dapat ditetapkan menggunakan karakter pipa (|
) untuk memisahkan tempat (misalnyaBerlin,Germany|Paris,France
). Jumlah titik jalan yang diizinkan bervariasi menurut platform tempat link terbuka, dengan maksimal tiga titik jalan didukung di browser seluler, dan maksimum sembilan titik jalan didukung jika tidak. Titik jalan ditampilkan di peta dengan urutan yang sama dengan yang tercantum di URL. Setiap titik jalan bisa berupa nama tempat, alamat, atau koordinat garis lintang/bujur yang dipisahkan koma. String harus dienkode ke URL, sehingga titik jalan seperti "Berlin,Jerman|Paris,Prancis" harus dikonversi menjadiBerlin%2CGermany%7CParis%2CFrance
.Catatan:
- Titik jalan tidak didukung di semua produk Google Maps; dalam kasus tersebut, parameter ini akan diabaikan.
- Parameter ini bersifat opsional, kecuali jika Anda menentukan
waypoint_place_ids
di URL Anda. Jika memilih untuk menentukanwaypoint_place_ids
, Anda juga harus menyertakanwaypoints
dalam URL.
waypoint_place_ids
(opsional): ID tempat adalah ID tekstual yang secara unik mengidentifikasi tempat.Waypoint_place_ids
memungkinkan Anda memberikan daftar ID tempat agar cocok dengan daftarwaypoints
. ID tempat harus dicantumkan dalam urutan yang sama dengan titik jalan, dan dipisahkan menggunakan karakter pipa "|
" ( dienkode ke URL sebagai%7C
). Jika Anda mencoba menentukan tempat usaha tertentu secara pasti, ID tempat adalah jaminan terbaik bahwa Anda akan menautkan ke tempat yang tepat. URL yang menggunakan parameter ini juga harus menyertakanwaypoints
.avoid
(opsional): Menetapkan fitur yang harus dihindari oleh rute. Kolom ini dapat disetel ke satu atau beberapa opsi ini, yang dipisahkan dengan karakter koma ",
" ( dienkode URL sebagai%2C
):ferries
highways
tolls
Contoh rute
URL berikut meluncurkan peta dalam mode rute dan memberikan formulir yang memungkinkan pengguna memasukkan tempat asal dan tujuan.
https://www.google.com/maps/dir/?api=1
Contoh berikut meluncurkan peta dengan rute sepeda dari Space Needle ke Pike Place Market, di Seattle, WA.
Contoh berikut meluncurkan peta dengan rute jalan kaki dari Google di Sydney, Australia, ke Queen Victoria Building.
Menampilkan peta
Tindakan peta akan menampilkan peta tanpa penanda atau rute.
Membentuk URL peta
https://www.google.com/maps/@?api=1&map_action=map¶meters
Parameter
map_action=map
(wajib): Menentukan jenis tampilan peta yang akan ditampilkan. Maps dan Street View memiliki endpoint yang sama. Untuk memastikan peta ditampilkan,map_action
harus ditetapkan sebagaimap
.center
(opsional): Menentukan pusat jendela peta, dan menerima koordinat garis lintang/bujur sebagai nilai yang dipisahkan koma (misalnya,-33.8569,151.2152
).zoom
(opsional): Menetapkan tingkat zoom awal peta. Nilai yang diterima adalah bilangan bulat mulai dari 0 (seluruh dunia) hingga 21 (masing-masing bangunan). Batas atas dapat bervariasi bergantung pada data peta yang tersedia di lokasi yang dipilih. Defaultnya adalah 15.basemap
(opsional): Menentukan jenis peta yang akan ditampilkan. Nilainya dapat beruparoadmap
(default),satellite
, atauterrain
.layer
(opsional): Menentukan lapisan tambahan untuk ditampilkan di peta, jika ada. Nilainya dapat berupa salah satu dari berikut ini:none
(default),transit
,traffic
, ataubicycling
.
Contoh peta
URL contoh ini meluncurkan Google Maps default, yang berpusat pada lokasi pengguna saat ini.
https://www.google.com/maps/@?api=1&map_action=map
Contoh berikut menampilkan peta yang berpusat di Katoomba, NSW, Australia (di -33.712206,150.311941
), dan menetapkan parameter zoom
dan basemap
opsional.
Menampilkan panorama Street View
Tindakan panorama memungkinkan Anda meluncurkan penampil untuk menampilkan gambar Street View sebagai panorama interaktif. Setiap panorama Street View memberikan tampilan 360 derajat penuh 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). Tindakan panorama meluncurkan penampil yang merender panorama yang dihasilkan sebagai bola dunia dengan kamera di tengahnya. Anda dapat memanipulasi kamera untuk mengontrol zoom dan orientasi kamera.
Google Street View menyediakan tampilan panorama dari lokasi yang ditentukan hingga area cakupannya. Photospheres kontribusi pengguna dan koleksi khusus Street View juga tersedia.
Membentuk URL Street View
https://www.google.com/maps/@?api=1&map_action=pano¶meters
Parameter
map_action=pano
(wajib): Menentukan jenis tampilan yang akan ditampilkan. Maps dan Street View memiliki endpoint yang sama. Untuk memastikan panorama ditampilkan,action
harus ditetapkan sebagaipano
.
Salah satu parameter URL berikut juga diperlukan:
viewpoint
: Penampil menampilkan panorama yang difoto yang terdekat dengan lokasiviewpoint
, yang ditetapkan sebagai koordinat garis lintang/bujur yang dipisahkan koma (misalnya 46.414382,10.013988). Karena gambar Street View diperbarui secara berkala, dan fotonya mungkin diambil dari posisi yang sedikit berbeda, maka mungkin lokasi Anda beralih ke panorama yang berbeda saat gambar diperbarui.pano
: ID panorama spesifik dari gambar yang akan ditampilkan. Jika menentukanpano
, Anda juga dapat menentukanviewpoint
.viewpoint
hanya digunakan jika Google Maps tidak dapat menemukan ID panorama. Jikapano
ditentukan tetapi tidak ditemukan, danviewpoint
TIDAK ditentukan, tidak ada gambar panorama yang akan ditampilkan. Sebaliknya, Google Maps akan terbuka dalam mode default, yang menampilkan peta yang berpusat pada lokasi pengguna saat ini.
Parameter URL berikut ini bersifat opsional:
heading
: Menunjukkan judul kompas pada kamera dalam derajat, searah jarum jam dari Utara. Nilai yang dapat diterima adalah dari -180 hingga 360 derajat. Jika dihilangkan, judul default akan dipilih berdasarkan sudut pandang (jika ditentukan) kueri dan lokasi gambar yang sebenarnya.pitch
: Menentukan sudut, naik atau turun, pada kamera. Pitch ditentukan dalam derajat mulai dari -90 hingga 90. Nilai positif akan menaikkan sudut kamera, sedangkan nilai negatif akan menurunkan sudut kamera. 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.fov
: Menentukan ruang pandang horizontal gambar. Ruang pandang dinyatakan dalam derajat, dengan rentang 10 - 100. Nilai defaultnya adalah 90. Saat menangani area pandang yang berukuran tetap, ruang pandang dianggap sebagai tingkat zoom, dengan angka yang lebih kecil menunjukkan tingkat zoom yang lebih tinggi.
Contoh Street View
Dua contoh pertama menampilkan panorama Menara Eiffel. Contoh satu
hanya menggunakan viewpoint
untuk lokasi, dan menetapkan parameter
heading
, pitch
, dan fov
opsional. Sebagai perbandingan, contoh dua menggunakan ID pano
serta parameter yang sama yang ditetapkan di contoh pertama. Contoh ketiga menampilkan gambar panorama dalam ruangan.
Contoh 1: Hanya menggunakan viewpoint
untuk menentukan lokasi.
Contoh 2: Menggunakan ID pano
serta lokasi viewpoint
.
ID pano
lebih diprioritaskan daripada viewpoint
.
Dalam contoh ini, ID panorama ditemukan, sehingga viewpoint
diabaikan. Perhatikan bahwa gambar panorama yang ditampilkan untuk ID pano
sedikit berbeda, dan lebih baru, daripada gambar yang ditemukan hanya menggunakan viewpoint
.
Contoh 3: Menampilkan panorama interior restoran Sarastro di London, Inggris Raya, yang ditentukan dengan ID panorama.
https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA
Menemukan ID panorama
Untuk menemukan ID gambar panorama tertentu, ada beberapa metode yang bisa Anda gunakan.
- Untuk JavaScript, gunakan class StreetViewPanorama.
- Untuk Android, gunakan class publik StreetViewPanoramaLocation.
- Untuk iOS, gunakan class GMSPanorama.
- Anda juga dapat membuat permintaan metadata menggunakan Google Street View Image API. Permintaan metadata gambar menyediakan data tentang panorama Street View, termasuk ID panorama.
Contoh lainnya
Contoh rute menggunakan titik jalan
Contoh rute berikut meluncurkan Google Maps dan menampilkan rute mobil dari Paris, Prancis ke Cherbourg, Prancis, yang memilih rute melalui titik jalan berikut:
Kota, Negara | Nama Tempat | ID Tempat |
---|---|---|
1. Versailles, Prancis | Istana Versailles | ChiJdUyx15R95kcRj85ZX8H8OAU |
2. Chartres, Prancis | Katedral Chartres | ChIJKzGHdEgM5EcR_OBTT3nQoEA |
3. Le Mans, Prancis | Katedral Saint Julian of Le Mans | ChIJG2LvQNCI4kcRKXNoAsPi1Mc |
4. Caen, Prancis | Kastil Caen | Anak-anak |
Pada contoh URL, titik jalan didefinisikan dengan cara yang berbeda sehingga Anda dapat membandingkan perbedaan tampilan titik jalan pada peta yang dihasilkan.
Contoh 1: Titik jalan didefinisikan sebagai Kota, Negara:
Contoh 2: Titik jalan didefinisikan sebagai nama tempat tertentu:
Contoh 3: Titik jalan ditetapkan sebagai Kota, Negara, dan juga memberikan
waypoint_place_ids
untuk tempat usaha tertentu di setiap titik jalan:
Contoh 4: Menentukan titik jalan sebagai Kota, Negara, tetapi mencantumkan titik jalan dalam urutan yang berbeda dibandingkan dengan contoh sebelumnya. Menunjukkan bahwa peta menampilkan titik jalan sesuai urutan yang tercantum di URL.
Contoh peta
Menampilkan peta dengan basemap
(satelit) dan layer
(transit) yang ditentukan.
Contoh Street View
Menampilkan panorama Street View menggunakan kunci gambar FIFE sebagai ID pano
. Perhatikan
bahwa ID pano
diawali dengan F:.