Praktik terbaik menggunakan Street View Static API

Kumpulan antarmuka HTTP, API web statis Google Maps Platform membuat gambar untuk disematkan langsung di halaman web Anda.

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

Panduan ini menjelaskan beberapa praktik umum yang berguna untuk menyiapkan permintaan layanan gambar dan web serta memproses respons layanan. Untuk mengetahui informasi selengkapnya tentang Street View Static API, lihat panduan developer.

Street View Static API berfungsi seperti API web statis, sedangkan layanan metadata berfungsi sebagai layanan web. Untuk mengetahui informasi selengkapnya tentang layanan metadata, lihat Metadata gambar Street View.

Apa itu API web statis?

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 gambar berdasarkan parameter URL yang dikirim menggunakan permintaan HTTPS standar.

Permintaan API Street View Static standar memiliki bentuk berikut:

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

Apa yang dimaksud dengan layanan web?

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

Layanan web Maps API menggunakan permintaan HTTP atau HTTPS ke URL tertentu, meneruskan parameter URL atau data POST berformat JSON sebagai argumen ke layanan. Umumnya, layanan ini menampilkan data dalam isi respons sebagai JSON untuk diuraikan atau diproses oleh aplikasi Anda.

Permintaan Metadata Street View Static API memiliki bentuk berikut:

https://maps.googleapis.com/maps/api/streetview/parameters

Akses SSL dan TLS

HTTPS diperlukan untuk semua permintaan Google Maps Platform yang menggunakan kunci API atau berisi data pengguna. Permintaan yang dilakukan melalui HTTP yang berisi data sensitif mungkin 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.

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:

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:

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 Google API yang sopan

Klien API yang didesain dengan buruk dapat menimbulkan beban berat pada internet dan server. Bagian ini berisi praktik terbaik untuk klien API. Mengikuti praktik terbaik ini dapat membantu mencegah aplikasi Anda diblokir karena penyalahgunaan API yang tidak disengaja.

Backoff eksponensial

Dalam kasus yang jarang terjadi, permintaan Anda mungkin mengalami masalah; Anda mungkin menerima kode respons HTTP 4xx atau 5xx, atau koneksi TCP mungkin gagal di suatu tempat antara klien Anda dan server Google. Sering kali, permintaan perlu dicoba lagi karena permintaan lanjutan mungkin berhasil saat permintaan awal gagal. Namun, jangan berulang kali membuat permintaan ke server Google. Perilaku perulangan ini dapat membebani jaringan antara klien dan Google, sehingga menyebabkan masalah bagi banyak pihak.

Pendekatan terbaik adalah mencoba ulang dengan meningkatkan waktu tunda antar percobaan. Penundaan biasanya meningkat dengan faktor perkalian pada setiap percobaan, pendekatan yang dikenal sebagai backoff eksponensial.

Misalnya, pertimbangkan aplikasi yang 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 menunjukkan cara membuat permintaan dengan jeda eksponensial:

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

# The maps_key defined in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


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

Pastikan tidak ada kode percobaan ulang yang lebih tinggi dalam rantai panggilan aplikasi yang menyebabkan permintaan berulang secara berurutan.

Permintaan yang disinkronkan

Sejumlah besar permintaan yang disinkronkan ke API Google dapat terlihat seperti serangan Distributed Denial-of-Service (DDoS) pada infrastruktur Google, dan akan ditangani sebagaimana mestinya. Untuk menghindari masalah ini, pastikan permintaan API tidak disinkronkan antar-klien.

Misalnya, pertimbangkan aplikasi yang menampilkan waktu di zona waktu saat ini. Aplikasi ini mungkin menyetel alarm di sistem operasi klien untuk mengaktifkannya di awal menit sehingga waktu yang ditampilkan dapat diperbarui. Jangan melakukan panggilan API apa pun di aplikasi sebagai bagian dari pemrosesan yang terkait dengan alarm tersebut.

Melakukan panggilan API sebagai respons terhadap alarm tetap tidak baik karena akan menyebabkan panggilan API disinkronkan ke awal menit, bahkan di antara perangkat yang berbeda, dan bukan didistribusikan secara merata dari waktu ke waktu. Aplikasi yang didesain dengan buruk yang melakukan hal ini akan menghasilkan lonjakan traffic hingga 60 kali lipat dari tingkat normal di awal setiap menit.

Sebagai gantinya, Anda dapat mendesain aplikasi agar memiliki alarm kedua yang disetel ke waktu yang dipilih secara acak. Saat alarm kedua ini diaktifkan, aplikasi akan memanggil API yang diperlukan dan menyimpan hasilnya. Saat memperbarui tampilan di awal menit, aplikasi menggunakan hasil yang disimpan sebelumnya, bukan memanggil API lagi. Dengan pendekatan ini, panggilan API tersebar secara merata dari waktu ke waktu. Selain itu, panggilan API tidak menunda rendering saat tampilan diperbarui.

Selain awal menit, jangan menargetkan waktu sinkronisasi umum lainnya, seperti awal jam dan awal setiap hari pada tengah malam.

Memproses respons

Karena format persis setiap respons terhadap permintaan layanan web tidak dijamin—beberapa elemen mungkin tidak ada atau berada di beberapa lokasi—jangan menganggap bahwa format yang ditampilkan untuk respons tertentu sama dengan format untuk kueri yang berbeda. Sebagai gantinya, proses respons dan pilih nilai yang sesuai dengan menggunakan ekspresi.

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

Layanan web Google Maps memberikan respons yang dapat dipahami, tetapi tidak mudah digunakan. Saat menjalankan kueri, daripada menampilkan sekumpulan data, Anda mungkin ingin mengekstrak beberapa nilai tertentu. Secara umum, parsing respons dari layanan web dan ekstrak hanya nilai yang Anda minati.

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.