Praktik Terbaik Menggunakan Layanan Web Places Insights API

Layanan web Google Maps Platform adalah kumpulan antarmuka HTTP untuk layanan Google yang menyediakan data geografis untuk aplikasi peta Anda.

Panduan ini menjelaskan beberapa praktik umum yang berguna untuk menyiapkan permintaan layanan web dan memproses respons layanan. Lihat panduan developer untuk dokumentasi lengkap Places Insights API.

Apa yang dimaksud dengan layanan web?

Layanan web Google Maps Platform adalah antarmuka untuk meminta data Maps API dari layanan eksternal dan menggunakan data dalam aplikasi Maps Anda. Layanan ini didesain untuk digunakan bersama peta, sesuai dengan Pembatasan Lisensi dalam Persyaratan Layanan Google Maps Platform.

Layanan web Maps API menggunakan permintaan HTTP(S) ke URL tertentu, dengan meneruskan parameter URL dan/atau data POST berformat JSON sebagai argumen ke layanan. Biasanya, layanan ini menampilkan data dalam isi respons sebagai JSON untuk pemrosesan dan/atau pemrosesan oleh aplikasi Anda.

Contoh berikut menunjukkan URL permintaan GET REST:

AN ACTUAL API CALL INCLUDING THE API_KEY&key=API_KEY

Catatan: Semua aplikasi Places Insights 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 URI permintaan ke URL 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.

Penggunaan Moderat Google API

Klien API yang tidak dirancang dengan baik dapat membuat beban lebih dari yang diperlukan pada Internet dan server Google. Bagian ini berisi beberapa praktik terbaik untuk klien API. Dengan mengikuti praktik terbaik ini, Anda dapat menghindari aplikasi Anda diblokir karena penyalahgunaan API yang tidak disengaja.

Backoff Eksponensial

Dalam kasus yang jarang, bisa terjadi sesuatu yang salah saat melayani permintaan Anda; Anda dapat menerima kode respons HTTP 4XX atau 5XX, atau koneksi TCP dapat mengalami kegagalan antara klien Anda dan server Google. Sering kali, sebaiknya coba lagi permintaan karena permintaan tindak lanjut mungkin berhasil saat permintaan asli gagal. Namun, penting untuk tidak membuat loop berulang saat membuat permintaan ke server Google. Perilaku loop ini dapat menyebabkan kelebihan beban pada jaringan antara klien Anda dengan Google yang menyebabkan masalah bagi berbagai pihak.

Pendekatan terbaik adalah mencoba ulang dengan meningkatkan waktu tunda antar percobaan. Biasanya, waktu tunda ditingkatkan dengan faktor perkalian pada setiap percobaan, pendekatan ini dikenal sebagai Backoff Eksponensial.

Misalnya, pertimbangkan aplikasi yang ingin membuat permintaan ini ke Time Zone API:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Contoh Python berikut menampilkan cara membuat permintaan dengan backoff eksponensial:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Anda juga harus berhati-hati bahwa tidak ada percobaan ulang kode yang lebih tinggi di rantai panggilan aplikasi yang menyebabkan permintaan berulang dalam urutan yang cepat.

Permintaan yang Disinkronkan

Sejumlah besar permintaan yang disinkronkan ke Google API bisa tampak seperti serangan DDoS (Distributed Denial of Service) pada infrastruktur Google, dan akan diperlakukan sebagai DDoS. Untuk menghindarinya, Anda harus memastikan bahwa permintaan API tidak disinkronkan antara klien.

Misalnya, pertimbangkan aplikasi yang menampilkan waktu dalam zona waktu saat ini. Aplikasi ini mungkin akan menyetel alarm dalam sistem operasi klien yang membangunkannya saat menit dimulai sehingga waktu yang ditampilkan bisa diperbarui. Aplikasi harus tidak melakukan panggilan API apa pun sebagai bagian dari pemrosesan yang terkait dengan alarm tersebut.

Membuat panggilan API sebagai respons terhadap alarm tetap dianggap buruk karena menyebabkan panggilan API disinkronkan ke awal menit, bahkan antara perangkat yang berbeda, bukannya didistribusikan secara merata dari waktu ke waktu. Aplikasi yang dirancang dengan buruk yang melakukan ini akan menghasilkan lonjakan traffic sebesar enam puluh kali dari tingkat normal di awal setiap menit.

Sebagai gantinya, satu rancangan yang mungkin baik adalah menyetel alarm kedua ke waktu terpilih yang acak. Saat alarm kedua terpicu, aplikasi memanggil API apa pun yang diperlukannya dan menyimpan hasilnya. Saat aplikasi ingin memperbarui tampilannya di awal menit, aplikasi menggunakan hasil yang disimpan sebelumnya, bukan memanggil API kembali. Dengan pendekatan ini, panggilan API tersebar dengan rata dari waktu ke waktu. Selain itu, panggilan API tidak menunda rendering saat tampilan sedang diperbarui.

Selain awal menit, waktu sinkronisasi umum lainnya yang harus Anda perhatikan agar tidak ditarget adalah di awal jam, dan awal setiap hari pada tengah malam.

Memproses Respons

Catatan: Karena format yang tepat dari setiap respons dengan permintaan layanan web tidak dijamin (beberapa elemen mungkin hilang atau ada di beberapa lokasi), Anda tidak boleh menganggap bahwa format yang ditampilkan untuk setiap respons yang diberikan akan sama untuk kueri yang berbeda. Sebagai gantinya, Anda harus memproses respons dan memilih nilai yang sesuai melalui ekspresi.

Bagian ini membahas cara mengekstrak nilai-nilai ini secara dinamis dari respons layanan web.

Layanan web Google Maps menyediakan respons yang mudah dipahami, tetapi tidak begitu ramah pengguna. Saat melakukan kueri, dari pada menampilkan satu set data, mungkin lebih baik mengekstrak beberapa nilai tertentu. Biasanya, Anda ingin mem-parse respons dari layanan web dan hanya mengekstrak nilai-nilai yang Anda perlukan.

Skema penguraian yang Anda gunakan bergantung pada apakah Anda menampilkan output dalam JSON. Respons JSON, yang sudah dalam bentuk objek JavaScript, dapat diproses dalam JavaScript itu sendiri di klien.