Batas penggunaan untuk Layanan Web Google Maps APIs

Laman ini hanya untuk pelanggan yang memiliki lisensi sebelumnya dari Maps APIs for Work atau lisensi Maps API for Business. Laman ini tidak berlaku untuk pelanggan yang memiliki Google Maps APIs Premium Plan baru, yang tersedia pada Januari 2016.

Desember 2011

Penggunaan layanan web Google Maps APIs tunduk pada batas tertentu dari jumlah permintaan per jangka waktu 24 jam. Permintaan yang dikirim melebihi batas tersebut akan menerima pesan kesalahan.

Batas penggunaan didokumentasikan dalam Google Maps APIs for Work FAQ untuk Lisensi Sebelumnya.

Artikel ini ditujukan bagi pelanggan Google Maps APIs for Work yang mencapai batas tersebut dan mungkin perlu mengoptimalkan aplikasi untuk menggunakan layanan web secara lebih efisien.

Dasar-Dasar

Google Maps menyediakan layanan web sebagai antarmuka untuk meminta data Google maps yang akan digunakan dalam aplikasi Anda. Layanan ini hanya bisa digunakan bersamaan dengan peta Google; dilarang menggunakan data dari layanan ini tanpa menampilkannya pada peta Google. Untuk keterangan lebih lengkap, silakan baca Pembatasan Lisensi dari Ketentuan Layanan Google Maps APIs.

Ada dua tipe kuota yang membatasi penggunaan layanan web Google Maps APIs: jangka panjang (kuota per hari) dan jangka pendek (kuota kecepatan permintaan). Jika Anda melebihi batas penggunaan atau menyalahgunakan layanan, maka layanan web akan mengembalikan pesan kesalahan tertentu. Jika Anda berulang kali melebihi batas, akses Anda terhadap layanan web bisa diblokir. Ada kemungkinan juga menerima respons 403 Forbidden.

Catatan: batas berbeda diberlakukan untuk API sisi-klien. Maps JavaScript API adalah sesi per peta yang dibatasi kecepatan, sehingga permintaan didistribusikan ke semua pengguna. Hal ini membuat penggunaan berbasis browser bisa diskalakan sesuai pertumbuhan jumlah pengguna Anda. Untuk informasi cara memilih antara layanan web sisi-server dan sisi-klien yang setara, silakan rujuk ke dokumen Strategi Geocoding.

Masalah

Anda bisa melebihi batas penggunaan layanan web Google Maps APIs dengan:

  • Mengirimkan terlalu banyak permintaan per hari.
  • Mengirimkan permintaan terlalu cepat, yaitu terlalu banyak permintaan per detik.
  • Mengirimkan permintaan terlalu cepat dalam waktu yang terlalu lama atau menyalahgunakan layanan web.
  • Melebihi batas penggunaan lain, mis. titik per permintaan di Google Maps Elevation API.

Melebihi batas penggunaan

Jika melebihi batas penggunaan, Anda akan mendapatkan kode status OVER_QUERY_LIMIT sebagai respons.

Ini berarti layanan web akan berhenti merespons secara normal dan beralih hanya mengembalikan kode status OVER_QUERY_LIMIT hingga penggunaan berlebih diperbolehkan lagi. Ini bisa terjadi:

  • Dalam beberapa detik, jika diterima kesalahan karena aplikasi Anda mengirimkan terlalu banyak permintaan per detik.
  • Dalam waktu 24 jam berikutnya, jika diterima kesalahan karena aplikasi Anda mengirimkan terlalu banyak permintaan per hari. Kuota harian direset tengah malam, Waktu Pasifik.

Siaran layar ini menyediakan penjelasan langkah-demi-langkah perlambatan permintaan dan penanganan kesalahan secara benar, yang bisa diterapkan ke semua layanan web.

Setelah menerima respons dengan kode status OVER_QUERY_LIMIT, aplikasi Anda harus menentukan batas penggunaan yang telah terlampaui. Hal ini bisa dilakukan dengan memberi jeda selama 2 detik dan mengirim kembali permintaan yang sama. Jika kode status masih OVER_QUERY_LIMIT, aplikasi Anda akan mengirim terlalu banyak permintaan per hari. Atau, aplikasi Anda mengirim terlalu banyak permintaan per detik.

Berikut adalah contoh implementasi di Python:

url = "MAPS_API_WEBSERVICE_URL"
attempts = 0
success = False

while success != True and attempts < 3:
  raw_result = urllib.urlopen(url).read()
  attempts += 1
  # The GetStatus function parses the answer and returns the status code
  # This function is out of the scope of this example (you can use a SDK).
  status = GetStatus(raw_result)
  if status == "OVER_QUERY_LIMIT":
    time.sleep(2)
    # retry
    continue
  success = True

if attempts == 3:
  # send an alert as this means that the daily limit has been reached
  print "Daily limit has been reached"

Catatan: Ada kemungkinan juga mendapatkan kesalahan OVER_QUERY_LIMIT:

Aplikasi harus memastikan batas-batas ini tidak tercapai sebelum mengirimkan permintaan.

Respons HTTP 403

Permintaan ke layanan web juga dapat menerima kesalahan HTTP 403 (Forbidden). Biasanya, ini terjadi karena tanda tangan URL tidak valid. Untuk memverifikasi ini, buang parameter client dan signature dan coba lagi:

  • Jika respons menunjukkan HTTP 200 (OK), tanda tangan adalah masalahnya.
    Ini tidak berhubungan dengan batas penggunaan; lihat Memecahkan masalah autentikasi di bagian Layanan Web dari dokumentasi Google Maps APIs for Work untuk detailnya.
  • Jika respons masih tetap kesalahan HTTP 403 (Forbidden), tanda tangan mungkin bukan masalahnya, ini bisa saja terkait dengan batas penggunaan.
    Ini artinya akses Anda ke layanan web telah diblokir dengan alasan aplikasi Anda sudah terlalu lama melebihi batas penggunaan atau menyalahgunakan layanan web. Silakan akses Google Cloud Support Portal jika Anda mengalami masalah ini. Informasi kontak juga tersedia pada laman Dukungan dan sumber daya.

Permintaan ke semua layanan web memerlukan tanda tangan URL. Permintaan juga akan ditolak dengan kesalahan HTTP 403 (Forbidden) saat menyertakan parameter client namun tidak terdapat parameter signature, atau sebaliknya.

Solusi

Masalah di atas bisa diselesaikan dengan menggabungkan dua pendekatan:

  1. Menurunkan penggunaan, dengan mengoptimalkan aplikasi untuk menggunakan layanan web secara lebih efisien.
  2. Meningkatkan batas penggunaan, bila memungkinkan, dengan membeli kuota tambahan untuk lisensi Google Maps APIs for Work Anda.

Artikel ini akan berfokus pada cara mengoptimalkan aplikasi untuk menggunakan layanan web secara lebih efisien.

Pemeriksaan kelogisan

Sebelum melompat ke detail tentang cara menggunakan layanan web secara lebih efisien, ada baiknya meluangkan waktu untuk memeriksa bahwa layanan dan lisensi yang tepat telah digunakan.

Memvalidasi kasus penggunaan Anda

Layanan web Google Maps APIs paling cocok digunakan untuk aplikasi yang tidak memiliki masukan real-time dari pengguna akhir atau apabila browser web tidak tersedia. Ini biasanya terjadi ketika Anda mendapatkan kumpulan data yang bersifat independen dari masukan pengguna. Misalnya, jika Anda memiliki database dengan kumpulan alamat tetap yang memerlukan geocoding, seperti kumpulan properti yang ditawarkan atau dijual di situs web real estate, atau kumpulan lokasi toko.

Bila menggunakan layanan web Google Maps APIs, semua permintaan diperhitungkan terhadap kuota (harian dan per-detik) dari ID klien Anda. Kuota ini bersifat global untuk semua ID klien, tidak peduli berapa banyak alamat IP yang dikirim oleh permintaan.

Menggunakan layanan Maps JavaScript API sisi-klien dalam browser dibatasi kecepatan per sesi peta. Itu berarti permintaan didistribusikan ke semua pengguna Anda dan diseimbangkan saat jumlah pengguna bertumbuh. Oleh karena itu, API sisi-klien selalu lebih disukai dan akan digunakan bila memungkinkan. Mereka paling cocok dipakai jika Anda mengumpulkan alamat dari pengguna yang memerlukan geocode secara real time, seperti melakukan penelusuran toko paling dekat dengan alamat rumah pengguna.

Untuk penjelasan lebih detail tentang topik ini, lihat dokumen Strategi Geocoding. Meskipun khusus untuk geocoding, rekomendasi dalam dokumen ini berlaku untuk semua layanan web, menjelaskan kapan Anda harus menggunakan layanan web sisi-server dan kapan Anda harus menggunakan layanan web sisi-klien yang setara.

Menggunakan lisensi Google Maps APIs for Work

Jika Anda memiliki lisensi Google Maps APIs for Work, pastikan permintaan Anda menyertakan ID klien dengan benar.

Pelanggan Google Maps APIs for Work diberikan batas penggunaan yang lebih tinggi untuk layanan web Google Maps APIs daripada pengguna API gratis. Guna mendapatkan keuntungan dari sini, aplikasi Anda harus menyetel parameter client dengan benar seperti yang dijelaskan dalam bagian Layanan Web dari panduan ini.

Aplikasi yang tidak menggunakan ID klien Google Maps APIs for Work dengan benar tidak akan diperlakukan sebagai Bisnis, tidak akan mendapat manfaat dari fitur dan kemampuan hanya-bisnis, tidak akan ditanggung oleh Google Maps APIs for Work SLA, tidak berhak memperoleh dukungan teknis dan akan tunduk pada Pembatasan Lisensi dari Ketentuan Layanan Google Maps APIs biasa.

Cara mengoptimalkan

Menggunakan layanan web secara lebih efisien bisa diringkas dalam dua tujuan utama: menurunkan penggunaan dengan mengirimkan permintaan hanya bila benar-benar dibutuhkan dan menyebarkan penggunaan secara merata agar tetap di bawah batas.

Buat cache hasil

Bagian 10.5.d dari Ketentuan Layanan Google Maps APIs menetapkan bahwa Anda boleh menyimpan Materi dalam jumlah terbatas semata-mata untuk tujuan meningkatkan kinerja Implementasi Google Maps APIs karena latensi jaringan (dan tidak bertujuan untuk mencegah Google melacak penggunaan secara akurat), dan hanya jika storage tersebut: bersifat temporer (dan tidak lebih dari 30 hari); aman; tidak memanipulasi atau menggabungkan bagian Materi atau Layanan; dan, tidak mengubah atribusi dengan cara apa pun.

Ini berarti Anda bisa secara temporer meng-cache respons layanan web untuk menghindari pengiriman permintaan ganda dalam rentang waktu yang singkat. Respons dari layanan web selalu menyertakan header HTTP Cache-Control untuk menunjukkan berapa lama hasil bisa di-cache, saat ini 24 jam:

Cache-Control: public, max-age=86400

Header ini harus selalu diperhatikan. Caching bisa diimplementasikan dengan menggunakan web proxy, yang harus melakukannya di luar kotak atau menggunakan implementasi Anda sendiri. Perlu diperhatikan juga bahwa beberapa pustaka klien HTTP juga meng-cache respons HTTP.

Untuk meningkatkan tingkat kecocokan cache, koordinat LatLng harus dinormalisasi dengan pembulatan ke 6 tempat desimal, yang menyediakan ketepatan sekitar 11 cm di sekitar khatulistiwa. Hasil dari layanan web tidak akan berbeda dengan menambahkan lebih banyak desimal, meskipun hal tersebut dapat menurunkan tingkat kecocokan cache.

Batasi permintaan

Aplikasi harus memperlambat permintaan agar tidak melebihi batas penggunaan, ingat bahwa ini berlaku untuk semua ID klien terlepas dari berapa banyak alamat IP yang dikirim permintaan.

Anda bisa memperlambat permintaan dengan menempatkannya dalam antrian untuk melacak kapan permintaan dikirim. Dengan batas kecepatan 10 QPS (kueri per detik), pada saat mengirimkan permintaan ke-11, aplikasi Anda harus memeriksa stempel waktu dari permintaan pertama lalu menunggu sampai 1 detik telah berlalu. Hal yang sama juga harus diterapkan pada batas harian.

Bahkan jika throttling diimplementasikan dengan benar, aplikasi harus mewaspadai respons dengan kode status OVER_QUERY_LIMIT. Jika respons tersebut diterima, gunakan mekanisme pause-and-retry yang dijelaskan pada bagian Melebihi batas penggunaan di atas untuk mendeteksi batas yang telah terlampaui.

Menangani backlog

Dengan throttling yang diimplementasikan dengan benar, permintaan ke layanan web tidak akan dikirim melebihi batas penggunaan. Namun, aplikasi mungkin menerima masukan dengan volume yang lebih besar atau kecepatan lebih tinggi daripada yang diizinkan oleh batas penggunaan layanan web. Ini bisa mengakibatkan antrean throttling meningkat secara signifikan, menciptakan backlog permintaan tertunda.

Aplikasi Anda bisa saja mencapai batas penggunaan harian saat memproses backlog yang besar. Jika throttling diimplementasikan dengan benar untuk batas harian, aplikasi akan berhenti mengirim permintaan; jika tidak, mengirimkan permintaan tambahan akan menjumpai respons dengan kode status OVER_QUERY_LIMIT. Pada kedua kasus tersebut, backlog tidak akan berkurang.

Jika volume permintaan rata-rata selama sehari atau seminggu masih di bawah batas penggunaan, aplikasi Anda seharusnya bisa melewati backlog saat masukan lebih rendah. Jika tidak, Anda mungkin perlu meningkatkan kapasitas harian untuk lisensi Google Maps APIs for Work Anda (lihat bagian berikutnya).

Ketika mengoptimalkan tidak lagi cukup

Jika Anda sudah mengimplementasikan semua optimalisasi di atas dan backlog permintaan terus-menerus bertambah, baik pada basis harian atau di setiap waktu sepanjang hari, Anda mungkin memang membutuhkan peningkatan batas penggunaan per-hari atau per-detik untuk lisensi Google Maps APIs for Work Anda . Dalam hal ini, silakan hubungi Account Manager Google Maps APIs for Work Anda untuk mendiskusikan pilihan yang tersedia.