Layanan Autocomplete (Baru) adalah layanan web yang menampilkan prediksi tempat dan prediksi kueri sebagai respons terhadap permintaan HTTP. Dalam permintaan, tentukan string penelusuran teks dan batas geografis yang mengontrol area penelusuran.
Layanan Autocomplete (Baru) dapat mencocokkan kata dan substring lengkap input, me-resolve nama tempat, alamat, dan plus code. Karena itu aplikasi dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi kueri dan tempat secara real time.
Respons dari Autocomplete API (Baru) dapat berisi dua jenis prediksi:
- Prediksi tempat: Tempat, seperti bisnis, alamat, dan lokasi menarik, berdasarkan string teks input dan area penelusuran yang ditentukan. Prediksi tempat ditampilkan secara default.
- Prediksi kueri: String kueri yang cocok dengan string teks input dan area penelusuran. Prediksi kueri tidak ditampilkan secara default. Gunakan parameter permintaan
includeQueryPredictions
untuk menambahkan prediksi kueri ke respons.
Misalnya, Anda memanggil API menggunakan string yang berisi sebagian input pengguna, "Sicilian piz", sebagai input untuk area penelusuran, dengan area penelusuran yang dibatasi pada San Francisco, CA. Respons tersebut kemudian berisi daftar prediksi tempat yang cocok dengan string penelusuran dan area penelusuran, seperti restoran bernama "Sicilian Pizza Kitchen", beserta detail tentang tempat tersebut.
Prediksi tempat yang ditampilkan didesain untuk ditampilkan kepada pengguna untuk membantu mereka memilih tempat yang diinginkan. Anda dapat membuat permintaan Place Details (Baru) untuk mendapatkan informasi selengkapnya tentang prediksi tempat yang ditampilkan.
Respons juga dapat berisi daftar prediksi kueri yang cocok dengan
string penelusuran dan area penelusuran, seperti "Sicilian Pizza & Pasta". Setiap prediksi kueri dalam respons menyertakan kolom text
yang berisi string penelusuran teks yang direkomendasikan. Gunakan string
tersebut sebagai input bagi
Text Search (Baru)
untuk melakukan penelusuran yang lebih mendetail.
API Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat memahami API dan opsi API:
Cobalah!Permintaan Autocomplete (Baru)
Permintaan Autocomplete (Baru) adalah permintaan POST HTTP ke URL berupa:
https://places.googleapis.com/v1/places:autocomplete
Teruskan semua parameter dalam isi permintaan JSON atau di header sebagai bagian dari permintaan POST. Contoh:
curl -X POST -d '{ "input": "pizza", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Tentang respons
Autocomplete (Baru) menampilkan objek JSON sebagai respons. Dalam respons:
- Array
suggestions
berisi semua prediksi tempat dan kueri secara berurutan berdasarkan relevansi yang dirasakan. Setiap tempat direpresentasikan oleh kolomplacePrediction
dan setiap kueri diwakili oleh kolomqueryPrediction
. - Kolom
placePrediction
berisi informasi mendetail tentang prediksi satu tempat, termasuk ID tempat dan deskripsi teks. - Kolom
queryPrediction
berisi informasi mendetail tentang satu prediksi kueri.
Objek JSON lengkap tersedia dalam bentuk:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 }] }, ... }, { "queryPrediction": { "text": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 }] }, ... } ...] }
Parameter wajib
-
input
String teks yang akan ditelusuri. Tentukan kata dan substring lengkap, nama tempat, alamat, dan plus code. Layanan Autocomplete (Baru) menampilkan kandidat berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang dirasakan.
Parameter opsional
-
includedPrimaryTypes
Suatu tempat hanya dapat memiliki satu jenis utama dari jenis yang tercantum dalam Tabel A atau Tabel B. Misalnya, jenis utama mungkin adalah
"mexican_restaurant"
atau"steak_house"
.Secara default, API menampilkan semua tempat berdasarkan parameter
input
, terlepas dari nilai jenis utama yang terkait dengan tempat tersebut. Batasi hasil dari jenis utama atau jenis utama tertentu dengan meneruskan parameterincludedPrimaryTypes
.Gunakan parameter ini untuk menentukan hingga lima nilai jenis dari Tabel A atau Tabel B. Tempat harus cocok dengan salah satu nilai jenis utama yang ditentukan agar dapat disertakan dalam respons.
Parameter ini juga dapat menyertakan salah satu dari
(regions)
atau(cities)
. Filter koleksi jenis(regions)
untuk area atau pembagian, seperti kawasan dan kode pos. Filter koleksi jenis(cities)
untuk tempat yang diidentifikasi Google sebagai kota.Permintaan ditolak dengan error
INVALID_REQUEST
jika:- Lebih dari lima jenis ditentukan.
- Jenis apa pun ditetapkan selain
(cities)
atau(regions)
. - Setiap jenis yang tidak dikenal akan ditentukan.
-
includeQueryPredictions
Jika
true
, responsnya mencakup prediksi tempat dan kueri. Nilai defaultnya adalahfalse
, yang berarti responsnya hanya menyertakan prediksi tempat. -
includedRegionCodes
Hanya sertakan hasil dari daftar region yang telah ditentukan, yang ditetapkan sebagai array yang berisi maksimal 15 nilai dua karakter ccTLD ("domain level teratas"). Jika dihilangkan, tidak ada batasan yang diterapkan pada respons. Misalnya, untuk membatasi region ke Jerman dan Prancis:
"includedRegionCodes": ["de", "fr"]
Jika Anda menentukan
locationRestriction
danincludedRegionCodes
, hasilnya berada di area perpotongan dari kedua setelan. -
inputOffset
Offset karakter Unicode berbasis nol yang menunjukkan posisi kursor di
input
. Posisi kursor dapat memengaruhi prediksi yang ditampilkan. Jika kosong, nilai defaultnya adalah panjanginput
. -
languageCode
Bahasa pilihan untuk menampilkan hasil. Hasil mungkin tersedia dalam bahasa campuran jika bahasa yang digunakan dalam
input
berbeda dengan nilai yang ditentukan olehlanguageCode
, atau jika tempat yang ditampilkan tidak memiliki terjemahan dari bahasa lokal kelanguageCode
.- Anda harus menggunakan kode bahasa IETF BCP-47 untuk menentukan bahasa pilihan.
-
Jika
languageCode
tidak diberikan, API akan menggunakan nilai yang ditentukan dalam headerAccept-Language
. Jika tidak ada yang ditentukan, defaultnya adalahen
. Jika Anda menetapkan kode bahasa yang tidak valid, API akan menampilkan errorINVALID_ARGUMENT
. - Bahasa yang dipilih memiliki pengaruh kecil pada serangkaian hasil yang dipilih API untuk ditampilkan, dan urutan ditampilkannya. Hal ini juga memengaruhi kemampuan API untuk mengoreksi kesalahan ejaan.
-
API ini mencoba menyediakan alamat yang dapat dibaca oleh pengguna dan populasi lokal, sekaligus mencerminkan input pengguna. Prediksi tempat diformat secara berbeda bergantung pada input pengguna dalam setiap permintaan.
-
Istilah yang cocok dalam parameter
input
akan dipilih terlebih dahulu, menggunakan nama yang selaras dengan preferensi bahasa yang ditunjukkan oleh parameterlanguageCode
jika tersedia, sedangkan yang menggunakan nama yang paling cocok dengan input pengguna. -
Alamat diformat dalam bahasa lokal, dalam skrip yang dapat dibaca oleh pengguna jika memungkinkan, hanya setelah istilah yang cocok dipilih agar cocok dengan istilah dalam parameter
input
. -
Semua alamat lain ditampilkan dalam bahasa pilihan, setelah istilah yang cocok dipilih agar cocok dengan istilah dalam parameter
input
. Jika nama tidak tersedia dalam bahasa pilihan, API akan menggunakan kecocokan terdekat.
-
Istilah yang cocok dalam parameter
locationBias atau locationRestriction
Anda dapat menentukan
locationBias
ataulocationRestriction
, tetapi tidak keduanya, untuk menentukan area penelusuran. BayangkanlocationRestriction
sebagai menentukan wilayah tempat hasil harus berada, danlocationBias
yang menentukan wilayah di mana hasilnya harus berada di dekat area tersebut, tetapi bisa berada di luar area tersebut.locationBias
Menentukan area yang akan ditelusuri. Lokasi ini berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan.
locationRestriction
Menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak akan ditampilkan.
Tentukan wilayah
locationBias
ataulocationRestriction
sebagai Area Pandang persegi panjang atau sebagai lingkaran.Lingkaran ditentukan dengan titik pusat dan jari-jari dalam meter. Radius harus antara 0,0 dan 50.000,0, inklusif. Nilai defaultnya adalah 0.0. Untuk
locationRestriction
, Anda harus menetapkan radius ke nilai yang lebih besar dari 0,0. Jika tidak, permintaan tidak akan menampilkan hasil.Contoh:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Persegi panjang adalah area tampilan garis lintang dan garis bujur, yang direpresentasikan sebagai dua yang secara diagonal berlawanan
low
dan titik tinggi. Area tampilan dianggap sebagai wilayah tertutup, yang berarti area tersebut menyertakan batasnya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat inklusif:- Jika
low
=high
, area pandang terdiri dari titik tunggal tersebut. - Jika
low.longitude
>high.longitude
, rentang bujur dibalik (area pandang melintasi garis bujur 180 derajat). - Jika
low.longitude
= -180 derajat danhigh.longitude
= 180 derajat, area pandang akan menyertakan semua bujur. - Jika
low.longitude
= 180 derajat danhigh.longitude
= -180 derajat, rentang bujur kosong.
low
danhigh
harus diisi, dan kotak yang direpresentasikan tidak boleh kosong. Area pandang kosong akan menyebabkan error.Misalnya, area pandang ini sepenuhnya mencakup New York City:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Jika
-
asal
Titik asal untuk menghitung jarak garis lurus ke tujuan (ditampilkan sebagai
distanceMeters
). Jika nilai ini dihilangkan, jarak garis lurus tidak akan ditampilkan. Harus ditetapkan sebagai koordinat lintang dan bujur:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Kode wilayah yang digunakan untuk memformat respons, yang ditetapkan sebagai nilai dua karakter ccTLD ("domain level teratas"). Sebagian besar kode ccTLD identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk), sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "Inggris Raya dan Irlandia Utara").
Jika Anda menetapkan kode wilayah yang tidak valid, API akan menampilkan error
INVALID_ARGUMENT
. Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku. -
sessionToken
Token sesi adalah string buatan pengguna yang melacak panggilan Autocomplete (Baru) sebagai "sesi". Autocomplete (Baru) menggunakan token sesi untuk mengelompokkan fase kueri dan pemilihan dari penelusuran pelengkapan otomatis pengguna ke dalam sesi terpisah untuk tujuan penagihan. Untuk informasi selengkapnya, lihat Token sesi.
Contoh Autocomplete (Baru)
Menggunakan locationRestriction dan locationBias
API ini menggunakan pembiasan IP secara default untuk mengontrol area penelusuran. Dengan pembiasan IP, API menggunakan
alamat IP perangkat untuk membiaskan hasil. Secara opsional, Anda dapat menggunakan
locationRestriction
atau locationBias
, tetapi tidak keduanya, untuk menentukan area yang akan ditelusuri.
locationRestriction
menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan
tidak akan ditampilkan. Pada contoh berikut, Anda menggunakan locationRestriction
untuk membatasi permintaan ke lingkaran dengan radius 5.000 meter yang berpusat di San Francisco:
curl -X POST -d '{ "input": "Amoeba", "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Semua hasil dari dalam area yang ditentukan terdapat dalam array suggestions
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
Dengan locationBias
, lokasi tersebut berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan. Pada contoh
berikutnya, Anda mengubah permintaan untuk menggunakan locationBias
:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Hasilnya sekarang berisi lebih banyak item, termasuk hasil di luar radius 5.000 meter:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
Menggunakan includePrimaryTypes
Gunakan parameter includedPrimaryTypes
untuk menentukan hingga lima nilai jenis dari
Tabel A,
Tabel B,
atau hanya (regions)
, atau hanya (cities)
. Tempat harus cocok dengan salah satu nilai jenis utama yang ditentukan agar dapat disertakan dalam respons.
Pada contoh berikut, Anda menentukan string input
"Sepak Bola" dan menggunakan parameter includedPrimaryTypes
untuk membatasi hasil pada tempat berjenis "sporting_goods_store"
:
curl -X POST -d '{ "input": "Soccer", "includedPrimaryTypes": ["sporting_goods_store"], "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Jika Anda menghapus parameter includedPrimaryTypes
, hasilnya dapat menyertakan tempat dari jenis yang tidak Anda inginkan, seperti "athletic_field"
.
Meminta prediksi kueri
Prediksi kueri tidak ditampilkan secara default. Gunakan parameter permintaan includeQueryPredictions
untuk menambahkan prediksi kueri ke respons. Contoh:
curl -X POST -d '{ "input": "Amoeba", "includeQueryPredictions": true, "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Array suggestions
sekarang berisi prediksi tempat dan prediksi kueri seperti yang ditunjukkan di atas dalam bagian Tentang respons. Setiap prediksi kueri
menyertakan kolom text
yang berisi string penelusuran teks yang direkomendasikan. Anda dapat membuat
permintaan Text Search (Baru)
untuk mendapatkan informasi selengkapnya tentang prediksi kueri yang ditampilkan.
Gunakan origin
Dalam contoh ini, sertakan origin
dalam permintaan sebagai koordinat lintang dan bujur.
Saat Anda menyertakan origin
, API akan menyertakan kolom distanceMeters
dalam
respons yang berisi jarak garis lurus dari origin
ke tujuan.
Contoh ini menyetel tempat asal ke pusat San Francisco:
curl -X POST -d '{ "input": "Amoeba", "origin": { "latitude": 37.7749, "longitude": -122.4194 }, "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Responsnya sekarang menyertakan distanceMeters
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
Cobalah!
API Explorer memungkinkan Anda membuat contoh permintaan sehingga Anda dapat memahami API dan opsi API.
- Pilih ikon API, , di sisi kanan halaman.
- Jika ingin, luaskan Show standard variables dan tetapkan parameter
fields
ke kolom mask. - Jika ingin, edit Isi permintaan.
- Pilih tombol Execute. Di jendela pop-up, pilih akun yang ingin digunakan untuk membuat permintaan.
Di panel API Explorer, pilih ikon luaskan, , untuk meluaskan jendela API Explorer.