Praktik Terbaik Menggunakan Maps Static API

Static web API Google Maps Platform adalah kumpulan antarmuka HTTP untuk Google layanan yang menghasilkan gambar yang dapat disematkan langsung di laman web Anda.

Panduan ini menjelaskan beberapa praktik umum yang berguna untuk menyiapkan permintaan gambar dan memproses respons layanan. Lihat panduan developer untuk melihat dokumentasi lengkap Maps Static API.

Apa itu Static Web API?

API web statis Google Maps Platform memungkinkan Anda menyematkan gambar Google Maps di halaman web tanpa memerlukan JavaScript atau pemuatan halaman dinamis. API web statis membuat mengenai parameter URL yang dikirim menggunakan permintaan HTTPS standar.

Permintaan Maps Static API umumnya merupakan permintaan formulir berikut:

  https://www.googleapis.com/staticmap/z/x/y?parameters

Catatan: Semua aplikasi Maps Static API memerlukan autentikasi. Dapatkan informasi selengkapnya tentang kredensial autentikasi.

Akses SSL/TLS

HTTPS diperlukan untuk semua permintaan Google Maps Platform yang menggunakan kunci API atau berisi data pengguna. Permintaan yang dibuat melalui HTTP yang berisi data sensitif dapat ditolak.

Membuat URL yang valid

Anda mungkin menganggap URL yang "valid" sudah jelas, tetapi kenyataannya tidak demikian. URL yang dimasukkan dalam kolom URL di browser, sebagai contoh, dapat berisi karakter khusus (misalnya "上海+中國"); browser harus menerjemahkan karakter tersebut secara internal ke dalam encoding yang berbeda sebelum melakukan transmisi. Dengan token yang sama, setiap kode yang menghasilkan atau menerima input UTF-8 dapat memperlakukan URL berisi karakter UTF-8 sebagai "valid", tetapi juga perlu menerjemahkan karakter tersebut sebelum mengirimnya ke server web. Proses ini disebut encoding URL atau encoding persen.

Perhatian: Browser dan/atau layanan dapat otomatis Mengenkode URL permintaan URI sebelum mengirim. Pada API yang menggunakan penandatanganan permintaan kriptografis, hal ini dapat menyebabkan tanda tangan menjadi tidak valid, jika encoding URL mengubah permintaan setelah penandatanganan. Untuk menghindari masalah ini, selalu encode URL string kueri Anda sebelum menandatangani permintaan.

Karakter khusus

Karakter khusus harus diterjemahkan karena semua URL harus sesuai dengan sintaksis yang ditentukan oleh spesifikasi Uniform Resource Identifier (URI). Dengan demikian, URL hanya boleh berisi sebagian karakter ASCII khusus: simbol alfanumerik yang sudah umum, dan beberapa karakter dengan fungsi khusus untuk digunakan sebagai karakter kontrol dalam URL. Tabel ini merangkum karakter tersebut:

Kumpulan	karakter	Penggunaan URL
Alfanumerik	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	String teks, penggunaan skema (http), port (8080), dll.
Tanpa fungsi khusus	- _ . ~	String teks
Dengan fungsi khusus	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	Karakter kontrol dan/atau String Teks

Saat membuat URL yang valid, Anda harus memastikan bahwa URL tersebut hanya berisi karakter yang ditampilkan dalam tabel. Penyesuaian URL untuk menggunakan kumpulan karakter ini biasanya menyebabkan dua masalah, yaitu masalah penghilangan dan masalah penggantian:

• Karakter yang ingin Anda tangani tidak termasuk dalam kumpulan karakter di atas. Misalnya, karakter dalam bahasa asing seperti 上海+中國 harus dienkode menggunakan karakter di atas. Menurut aturan umum, spasi (yang tidak diizinkan dalam URL) sering kali juga dinyatakan menggunakan karakter plus '+'.
• Karakter yang ada dalam kumpulan di atas merupakan karakter dengan fungsi khusus, tetapi harus digunakan secara literal. Misalnya, ? digunakan dalam URL untuk menunjukkan awal dari string kueri; jika Anda ingin menggunakan string "? and the Mysterians", Anda harus mengenkode karakter '?'.

Semua karakter yang akan dienkode ke URL dienkode menggunakan karakter '%' dan nilai heksadesimal dua karakter yang sesuai dengan karakter UTF-8. Misalnya, 上海+中國 di UTF-8 akan dienkode ke URL sebagai %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. String ? and the Mysterians akan dienkode ke URL sebagai %3F+and+the+Mysterians atau %3F%20and%20the%20Mysterians.

Karakter umum yang memerlukan encoding

Beberapa karakter umum yang harus dienkode adalah:

Karakter tidak aman	Nilai yang dienkode
Spasi	%20
"	%22
<	%3C
>	%3E
#	%23
%	%25
|	%7C

Mengonversi URL yang Anda terima dari input pengguna terkadang rumit. Misalnya, seorang pengguna dapat memasukkan alamat sebagai "5th&Main St." Biasanya, Anda harus membuat URL Anda dari bagian-bagiannya, memperlakukan setiap input pengguna sebagai karakter literal.

Selain itu, URL dibatasi hingga 16.384 karakter untuk semua layanan web Google Maps Platform dan Static Web API. Untuk sebagian besar layanan, batas karakter ini jarang tercapai. Namun, perhatikan bahwa layanan tertentu memiliki beberapa parameter yang dapat menghasilkan URL panjang.