Anda sudah siap!

Untuk mulai mengembangkan, masuklah ke dokumentasi developer kami.

Aktifkan Google Places API Web Service

Untuk membantu Anda memulai, kami akan memandu Anda melalui Google Developers Console untuk melakukan beberapa hal terlebih dahulu:

  1. Buat atau pilih sebuah proyek
  2. Aktifkan Google Places API Web Service
  3. Buat kunci yang sesuai
Lanjutkan

Place Autocomplete

Layanan Place Autocomplete adalah layanan web yang mengembalikan prediksi tempat sebagai respons terhadap permintaan HTTP. Permintaan ini menetapkan string penelusuran tekstual dan batas geografis opsional. Layanan ini bisa digunakan untuk menyediakan fungsionalitas pelengkapan otomatis bagi penelusuran geografis berbasis teks, dengan mengembalikan tempat seperti bisnis, alamat dan tempat menarik saat pengguna mengetikkannya.

Permintaan Place Autocomplete

Layanan Place Autocomplete adalah bagian dari Google Places API Web Service dan menggunakan bersama kunci API serta kuota dengan Google Places API Web Service.

Layanan Place Autocomplete bisa mencocokkan kata lengkap serta substring. Karena itu aplikasi bisa mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi tempat secara sambil-jalan.

Prediksi yang dikembalikan didesain untuk disajikan kepada pengguna guna membantu mereka dalam memilih tempat yang diinginkan. Anda bisa mengirim permintaan Place Details untuk informasi selengkapnya tentang tempat yang dikembalikan.

Permintaan Place Autocomplete adalah HTTP URL dengan bentuk berikut:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

dalam hal ini, output bisa berupa salah satu nilai berikut:

  • json (disarankan) menunjukkan keluaran dalam JavaScript Object Notation (JSON)
  • xml menunjukkan keluaran berupa XML

Diperlukan parameter tertentu untuk memulai permintaan Place Autocomplete. Sebagaimana standar dalam URL, semua parameter dipisah menggunakan karakter ampersand (&). Daftar parameter dan kemungkinan nilainya disebutkan di bawah ini.

Parameter yang diperlukan

  • input — String teks yang digunakan untuk menelusuri. Layanan Place Autocomplete akan mengembalikan bakal hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.
  • keykunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk keperluan manajemen kuota. Lihat Dapatkan kunci untuk informasi selengkapnya. Google Maps APIs Premium Plan pelanggan harus menggunakan proyek API yang telah dibuatkan untuk mereka sebagai bagian dari pembelian Premium Plan.

Parameter opsional

  • offset — Posisi, dalam istilah yang dimasukkan, karakter terakhir yang digunakan layanan untuk mencocokkan prediksi. Misalnya, jika memasukkan 'Google' dan offset-nya 3, layanan akan mencocokkannya pada 'Goo'. String yang ditetapkan oleh offset hanya dicocokkan dengan kata pertama dalam istilah yang dimasukkan. Misalnya, jika istilah yang dimasukkan adalah 'Google abc' dan offset-nya 3, layanan akan berusaha mencocokkannya dengan 'Goo abc'. Jika tidak ada offset yang diberikan, layanan ini akan menggunakan kata utuh. offset biasanya harus disetel ke posisi tanda penyisipan teks.
  • location — Titik yang Anda inginkan untuk mengambil informasi tempat. Harus ditetapkan sebagai garis lintang,garis bujur.
  • radius — Jarak (dalam meter) jangkauan untuk mengembalikan hasil pencarian tempat. Perhatikan, setelan radius membuat hasil condong ke area yang ditandai, namun mungkin tidak sepenuhnya membatasi hasil ke area yang ditetapkan. Lihat Pencondongan Lokasi dan Pembatasan Lokasi di bawah ini.
  • language — Kode bahasa, menunjukkan dalam bahasa apa hasilnya akan dikembalikan, jika memungkinkan. Penelusuran juga dicondongkan ke bahasa yang dipilih; mengakibatkan bahasa yang dipilih mungkin diberikan peringkat lebih tinggi. Lihat daftar bahasa yang didukung dan kodenya. Perhatikan, kami sering memperbarui bahasa yang didukung sehingga daftar ini mungkin tidak lengkap. Jika bahasa tidak diberikan, layanan Place Autocomplete akan berusaha menggunakan bahasa asli domain yang menjadi asal pengiriman permintaan.
  • types — Tipe hasil tempat yang akan dikembalikan. Lihat Tipe Tempat di bawah ini. Jika tidak ada tipe yang ditetapkan, maka akan dikembalikan semua tipe.
  • components — Pengelompokan tempat yang Anda perlukan untuk membatasi hasil. Saat ini, Anda bisa menggunakan components untuk memfilter berdasar negara. Negara harus diteruskan berupa dua karakter, kode negara yang kompatibel dengan ISO 3166-1 Alpha-2. Misalnya: components=country:fr akan membatasi hasilnya ke tempat-tempat di Prancis.
  • strictbounds — Hanya mengembalikan tempat yang persis berada dalam region yang didefinisikan oleh location dan radius. Pembatasan ini, bukan bias, maksudnya hasil di luar region ini tidak akan dikembalikan, bahkan jika cocok dengan masukan pengguna.

Mencondongkan Lokasi

Anda bisa mencondongkan hasil ke lingkaran yang ditetapkan dengan meneruskan parameter location dan radius. Ini akan menginstruksikan layanan Place Autocomplete agar lebih memilih menampilkan hasil dalam lingkaran itu. Hasil di luar area yang didefinisikan mungkin tetap ditampilkan. Anda bisa menggunakan parameter components untuk memfilter hasil agar hanya menampilkan tempat-tempat dalam negara yang ditetapkan.

Tip: Hasil penelusuran tempat usaha biasanya tidak memiliki peringkat yang cukup untuk ditampilkan dalam hasil bila area penelusurannya besar. Jika ingin tempat usaha Anda muncul dalam hasil campuran establishment/geocode, Anda bisa menetapkan radius yang lebih kecil. Atau, gunakan types=establishment untuk membatasi hasil ke tempat usaha saja.

Pembatasan Lokasi

Anda juga dapat membatasi hasil ke region yang didefinisikan oleh parameter location dan radius, dengan menambahkan parameter strictbounds. Ini menginstruksikan layanan Place Autocomplete agar hanya mengembalikan hasil dalam region itu.

Tipe Tempat

Anda bisa membatasi hasil permintaan Place Autocomplete pada tipe tertentu dengan meneruskan parameter types. Parameter ini menetapkan tipe atau kumpulan tipe, sebagaimana tercantum dalam tipe yang didukung di bawah ini. Jika tidak ada yang ditetapkan, semua tipe akan dikembalikan. Umumnya hanya satu tipe yang diperbolehkan. Pengecualiannya adalah Anda bisa dengan aman mencampur tipe geocode dan establishment, namun perhatikan, hal ini sama efeknya dengan tidak menetapkan tipe. Tipe yang didukung adalah:

  • geocode menginstruksikan layanan Place Autocomplete agar hanya mengembalikan hasil geocoding, bukan hasil bisnis. Biasanya, Anda menggunakan permintaan ini untuk memperjelas hasil saat lokasi yang ditetapkan mungkin tidak jelas.
  • address menginstruksikan layanan Place Autocomplete agar hanya mengembalikan hasil geocoding dengan alamat yang akurat. Biasanya, Anda menggunakan permintaan ini bila mengetahui pengguna akan mencari alamat lengkap yang telah ditetapkan.
  • establishment menginstruksikan layanan Place Autocomplete agar hanya mengembalikan hasil bisnis.
  • kumpulan tipe (regions) menginstruksikan layanan Places agar mengembalikan hasil apa saja yang cocok dengan tipe berikut:
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area_level_1
    • administrative_area_level_2
  • kumpulan tipe (cities) menginstruksikan layanan Places agar mengembalikan hasil yang cocok dengan locality atau administrative_area_level_3.

Contoh Permintaan Autocomplete

Permintaan untuk tempat usaha yang berisi string "Amoeba" dalam area yang berpusat di San Francisco, CA:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

Permintaan yang sama, dibatasi pada hasil yang berada dalam jarak 500 meter dari Ashbury St & Haight St, San Francisco:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

Permintaan untuk alamat yang berisi kata "Vict" dengan hasil dalam bahasa Prancis:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY

Permintaan untuk kota yang berisi kata "Vict" dengan hasil dalam bahasa Portugis Brasil:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY

Perhatikan, Anda perlu mengganti kunci API dalam contoh ini dengan kunci Anda sendiri.

Respons Place Autocomplete

Respons Place Autocomplete dikembalikan dalam format yang ditandai oleh flag output dalam jalur URL permintaan itu. Hasil di bawah ini adalah indikasi dari apa yang mungkin dikembalikan untuk kueri dengan parameter berikut:

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
XML
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

Respons JSON berisi dua elemen akar:

  • status berisi metadata yang diminta. Lihat Kode Status di bawah ini.
  • predictions berisi larik beberapa tempat, dengan informasi tentang tempat. Lihat Hasil Place Autocomplete untuk informasi tentang hasil ini. Google Places API Web Service mengembalikan hingga 5 hasil.

Yang menarik dalam hasil tersebut adalah elemen place_id, yang bisa digunakan untuk meminta detail lebih spesifik tentang tempat melalui kueri terpisah. Lihat Permintaan Place Details.

Lihat Memproses JSON dengan JavaScript untuk membantu mem-parse respons JSON.

Sebuah respons XML terdiri dari satu elemen <AutocompletionResponse> dengan dua tipe elemen anak:

  • Satu elemen <status> berisi metadata yang diminta. Lihat Kode Status di bawah ini.
  • Nol atau beberapa elemen <prediction>, masing-masing berisi informasi tentang satu tempat. Lihat Hasil Place Autocomplete untuk informasi tentang hasil ini. Google Places API Web Service mengembalikan hingga 5 hasil.

Kami menyarankan Anda menggunakan json sebagai flag output yang dipilih kecuali jika aplikasi Anda memerlukan xml karena suatu alasan. Pemrosesan struktur hierarki XML memerlukan kehati-hatian, jadi Anda perlu mereferensikan simpul dan elemen yang tepat. Lihat Mem-parse XML dengan XPath untuk membantu pemrosesan XML.

Kode Status

Bidang status dalam objek respons Place Autocomplete berisi status permintaan, dan mungkin berisi informasi debug untuk membantu Anda melacak penyebab gagalnya permintaan Place Autocomplete. Bidang status bisa berisi nilai-nilai berikut:

  • OK menunjukkan tidak terjadi kesalahan dan setidaknya satu hasil dikembalikan.
  • ZERO_RESULTS menunjukkan penelusuran berhasil namun tidak mengembalikan hasil. Ini bisa terjadi jika pada penelusuran itu diteruskan bounds di lokasi terpencil.
  • OVER_QUERY_LIMIT menunjukkan Anda telah melebihi kuota.
  • REQUEST_DENIED menunjukkan permintaan Anda ditolak, biasanya karena tidak ada parameter key yang tidak valid.
  • INVALID_REQUEST biasanya menunjukkan parameter input tidak ada.

Pesan Kesalahan

Bila layanan Places mengembalikan kode status selain dari OK, mungkin ada bidang error_message tambahan dalam objek respons. Bidang ini berisi informasi lebih detail tentang alasan di balik kode status yang diberikan.

Hasil Place Autocomplete

Bila layanan Places mengembalikan hasil JSON dari penelusuran, hasilnya akan dimasukkan dalam larik predictions. Bahkan jika layanan tidak mengembalikan hasil (seperti jika location ada di tempat terpencil), layanan masih mengembalikan sebuah larik predictions yang kosong. Respons XML terdiri dari nol atau beberapa elemen <prediction>.

Setiap hasil prediksi berisi bidang-bidang berikut:

  • description berisi nama yang bisa dibaca orang untuk hasil yang dikembalikan. Untuk hasil establishment, biasanya berisi nama bisnis.
  • place_id sebuah identifier tekstual yang secara unik mengidentifikasi tempat. Untuk mengambil informasi tentang tempat, teruskan identifier ini dalam bidang placeid pada permintaan Google Places API Web Service. Untuk informasi selengkapnya tentang ID tempat, lihat ringkasan ID tempat.
  • reference berisi token unik yang bisa Anda gunakan untuk mengambil informasi tambahan tentang tempat ini dalam permintaan Place Details. Meskipun token ini secara unik mengidentifikasi tempat, hal yang sebaliknya tidak berlaku. Sebuah tempat bisa memiliki banyak token referensi yang valid. Tidak dijamin bahwa token yang sama akan dikembalikan untuk suatu tempat pada penelusuran berbeda. Catatan: reference tidak digunakan lagi karena sudah ada place_id. Lihat pemberitahuan penghentian pada laman ini.
  • id berisi sebuah identifier unik dan stabil yang menandakan tempat ini. Identifier ini tidak boleh digunakan untuk mengambil informasi tentang tempat ini, namun bisa digunakan untuk mengkonsolidasikan data tentang tempat ini, dan untuk memverifikasi identitas tempat di semua penelusuran terpisah. Catatan: id tidak digunakan lagi karena sudah ada place_id. Lihat pemberitahuan penghentian pada laman ini.
  • terms berisi larik istilah yang mengidentifikasi setiap bagian keterangan yang dikembalikan (bagian dari keterangan biasanya diakhiri dengan koma). Setiap entri dalam larik memiliki bidang value, yang berisi teks istilah, dan bidang offset, yang mendefinisikan posisi awal istilah ini dalam keterangan, yang diukur dalam karakter Unicode.
  • types berisi larik tipe yang berlaku untuk tempat ini. Misalnya: [ "political", "locality" ] atau [ "establishment", "geocode" ].
  • matched_substrings berisi larik dengan nilai offset dan length. Ini menjelaskan lokasi istilah yang dimasukkan dalam teks hasil prediksi, sehingga istilah itu bisa disorot jika diinginkan.

Parameter sensor

Google Places API Web Service sebelumnya mengharuskan Anda menyertakan parameter sensor untuk menunjukkan apakah aplikasi Anda menggunakan sensor untuk menentukan lokasi pengguna. Parameter ini tidak lagi diperlukan.

Kirim masukan tentang...

location_on
Google Places API Web Service