Pengantar
Autocomplete (New) 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.
Autocomplete (New) dapat mencocokkan kata dan substring lengkap dari input, yang me-resolve nama tempat, alamat, dan Plus Codes. Oleh karena itu, aplikasi dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi tempat dan kueri secara real time.
Respons dari Autocomplete (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
includeQueryPredictionsuntuk menambahkan prediksi kueri ke respons.
Misalnya, Anda memanggil Autocomplete (Baru) menggunakan string yang berisi input pengguna parsial, "Sicilian piz", sebagai input, dengan area penelusuran yang dibatasi ke San Francisco, CA. Respons 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 dirancang untuk ditampilkan kepada pengguna guna membantu mereka memilih tempat yang diinginkan. Anda dapat membuat permintaan Place Details (New) 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 untuk
Text Search (Baru)
guna melakukan penelusuran yang lebih mendetail.
APIs Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat memahami API dan opsi API:
Permintaan Autocomplete (New)
Permintaan Autocomplete (New) adalah permintaan POST HTTP ke URL dalam bentuk:
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
Parameter yang didukung
Parameter |
Deskripsi |
|---|---|
String teks yang akan ditelusuri (kata lengkap, substring, nama tempat, alamat, Plus Codes). |
|
|
Daftar yang dipisahkan koma yang menentukan kolom mana yang akan ditampilkan dalam respons. |
Membatasi hasil ke tempat yang cocok dengan salah satu dari maksimal lima jenis utama yang ditentukan. |
|
Jika benar, menyertakan bisnis tanpa lokasi fisik (bisnis jasa sistem panggilan). Nilai defaultnya adalah false (salah). |
|
Jika benar, menyertakan prediksi tempat dan kueri dalam respons. Nilai defaultnya adalah false (salah). |
|
Array yang berisi hingga 15 kode negara dua karakter untuk membatasi hasil. |
|
Offset karakter Unicode berbasis nol dari posisi kursor dalam string input, yang memengaruhi prediksi. Nilai defaultnya adalah panjang input. |
|
Bahasa pilihan (kode IETF BCP-47) untuk hasil. Defaultnya adalah header Accept-Language atau 'en'. |
|
Menentukan area (lingkaran atau persegi panjang) untuk membiaskan hasil penelusuran, sehingga memungkinkan hasil di luar area tersebut. Tidak dapat digunakan dengan locationRestriction. |
|
Menentukan area (lingkaran atau persegi panjang) untuk membatasi hasil penelusuran. Hasil di luar area ini akan dikecualikan. Tidak dapat digunakan dengan locationBias. |
|
Titik awal (lintang, bujur) yang digunakan untuk menghitung jarak garis lurus (distanceMeters) ke tujuan yang diprediksi. |
|
Kode wilayah yang digunakan untuk memformat respons dan membiaskan saran (misalnya, 'uk', 'fr'). |
|
String buatan pengguna untuk mengelompokkan panggilan Autocomplete ke dalam sesi untuk tujuan penagihan. |
Tentang respons
Autocomplete (New) menampilkan objek JSON sebagai respons. Dalam respons:
- Array
suggestionsberisi semua tempat dan kueri yang diprediksi secara berurutan berdasarkan relevansinya yang terlihat. Setiap tempat diwakili oleh kolomplacePredictiondan setiap kueri diwakili oleh kolomqueryPrediction. - Kolom
placePredictionberisi informasi mendetail tentang satu prediksi tempat, termasuk ID tempat dan deskripsi teks.- Agar lebih cocok dengan input pengguna seperti yang diberikan dalam parameter
input, deskripsi teks prediksi tempat dapat menyertakan nama alternatif untuk tempat, jalan, dan komponen alamat lainnya. Nama alternatif ini mungkin berbeda dengan nama yang ditampilkan di kolomdisplayNamedan alamat hasil Place Details untuk ID tempat yang sama. - Dalam konteks ini, nama alternatif untuk beberapa tempat mungkin dalam
bahasa yang berbeda dari yang diharapkan berdasarkan parameter
languageCode, bergantung pada nama mana yang lebih cocok dengan input pengguna.
- Agar lebih cocok dengan input pengguna seperti yang diberikan dalam parameter
- Kolom
queryPredictionberisi informasi mendetail tentang satu prediksi kueri.
Objek JSON lengkap 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 yang diperlukan
input
String teks yang akan ditelusuri. Tentukan kata dan substring lengkap, nama tempat, alamat, dan Plus Codes. Layanan Autocomplete (New) menampilkan kandidat hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.
Parameter opsional
FieldMask
Tentukan daftar kolom yang akan ditampilkan dalam respons dengan membuat
mask kolom
respons. Teruskan mask kolom respons ke metode menggunakan header HTTP
X-Goog-FieldMask.
Tentukan daftar kolom saran yang dipisahkan koma untuk ditampilkan. Misalnya,
untuk mengambil suggestions.placePrediction.text.text dan
suggestions.queryPrediction.text.text saran.
X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
Gunakan * untuk mengambil semua kolom.
X-Goog-FieldMask: *
includeFutureOpeningBusinesses
Jika true, menampilkan bisnis
yang diperkirakan akan dibuka pada masa mendatang. Nilai defaultnya adalah false.
includedPrimaryTypes
Suatu tempat hanya dapat memiliki satu jenis utama dari jenis yang tercantum dalam
Tabel A
atau Tabel
B. Misalnya, jenis utama mungkin "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 agar memiliki
jenis utama atau jenis-jenis utama tertentu dengan meneruskan
parameter includedPrimaryTypes.
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 disertakan dalam respons.
Parameter ini juga dapat menyertakan salah satu dari (regions) atau
(cities). Kumpulan jenis (regions) memfilter
area atau divisi, seperti lingkungan dan kode pos. Kumpulan jenis (cities) memfilter tempat yang diidentifikasi Google sebagai kota.
Permintaan ditolak dengan error INVALID_REQUEST jika:
- Lebih dari lima jenis ditentukan.
- Jenis apa pun ditentukan selain
(cities)atau(regions). - Jenis yang tidak dikenal ditentukan.
includePureServiceAreaBusinesses
Jika ditetapkan ke true, respons akan menyertakan bisnis yang mengunjungi
atau mengirimkan langsung ke pelanggan, tetapi tidak memiliki lokasi bisnis
fisik. Jika ditetapkan ke false, API hanya akan menampilkan bisnis dengan
lokasi bisnis fisik.
includeQueryPredictions
Jika true, respons akan menyertakan prediksi tempat dan kueri. Nilai defaultnya adalah false, yang berarti respons hanya menyertakan prediksi tempat.
includedRegionCodes
Hanya sertakan hasil dari daftar wilayah yang ditentukan, yang ditetapkan sebagai array yang berisi hingga 15 nilai dua karakter ccTLD ("domain level teratas"). Jika dihilangkan, tidak ada batasan yang diterapkan pada respons. Misalnya, untuk membatasi wilayah ke Jerman dan Prancis:
"includedRegionCodes": ["de", "fr"]
Jika Anda menentukan locationRestriction dan includedRegionCodes,
hasilnya akan berada di area persimpangan kedua setelan tersebut.
inputOffset
Offset karakter Unicode berbasis nol yang menunjukkan posisi kursor di input.
Posisi kursor dapat memengaruhi prediksi yang ditampilkan. Jika kosong, setelan defaultnya adalah panjang input.
languageCode
Bahasa pilihan untuk menampilkan hasil. Hasilnya mungkin dalam bahasa campuran
jika bahasa yang digunakan di input berbeda dengan nilai yang ditentukan
oleh languageCode, atau jika tempat yang ditampilkan tidak memiliki
terjemahan dari bahasa lokal ke languageCode.
- Anda harus menggunakan kode bahasa IETF BCP-47 untuk menentukan bahasa pilihan.
-
Jika
languageCodetidak diberikan, API akan menggunakan nilai yang ditentukan di headerAccept-Language. Jika tidak ada yang ditentukan, defaultnya adalahen. Jika Anda menentukan kode bahasa yang tidak valid, API akan menampilkan errorINVALID_ARGUMENT. - Bahasa pilihan memiliki pengaruh kecil pada kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan kemunculannya. Hal ini juga memengaruhi kemampuan API untuk memperbaiki kesalahan ejaan.
-
Prediksi tempat diformat secara berbeda bergantung pada input pengguna di
setiap permintaan.
-
Istilah yang cocok dalam parameter
inputdipilih terlebih dahulu, menggunakan nama yang sesuai dengan preferensi bahasa yang ditunjukkan oleh parameterlanguageCodejika tersedia, atau menggunakan nama yang paling cocok dengan input pengguna. -
Nama tempat dapat diformat menggunakan nama alternatif agar sesuai dengan istilah dalam parameter
input, termasuk nama dalam bahasa selain bahasa yang ditunjukkan oleh parameterlanguageCode. -
Alamat jalan diformat dalam bahasa lokal, dalam skrip yang dapat dibaca oleh pengguna jika memungkinkan, hanya setelah istilah yang cocok dipilih agar sesuai dengan istilah dalam parameter
input. -
Semua alamat lainnya ditampilkan dalam bahasa pilihan, setelah
istilah yang cocok dipilih agar sesuai 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 atau locationRestriction,
tetapi tidak keduanya, untuk menentukan area penelusuran. Anggap
locationRestriction sebagai penentu wilayah tempat hasil harus
berada, dan locationBias sebagai penentu wilayah tempat
hasil harus berada di dekatnya, tetapi dapat 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 ditampilkan.
Tentukan wilayah locationBias atau locationRestriction sebagai
Area Pandang persegi panjang atau sebagai lingkaran.
Lingkaran ditentukan oleh titik pusat dan radius dalam meter. Radius harus antara 0,0 dan 50000,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 pandang lintang-bujur, yang direpresentasikan sebagai dua titik
lowdan titik tinggi yang berlawanan secara diagonal. Area pandang dianggap sebagai wilayah tertutup, yang berarti mencakup 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 satu titik tersebut. - Jika
low.longitude>high.longitude, rentang bujur akan dibalik (area pandang melintasi garis bujur 180 derajat). - Jika
low.longitude= -180 derajat danhigh.longitude= 180 derajat, area pandang akan mencakup semua bujur. - Jika
low.longitude= 180 derajat danhigh.longitude= -180 derajat, rentang bujur akan kosong.
lowdanhighharus diisi, dan kotak yang diwakili tidak boleh kosong. Area pandang yang kosong akan menghasilkan 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 awal untuk menghitung jarak garis lurus ke
tujuan (ditampilkan sebagai distanceMeters). Jika nilai ini
dihilangkan, jarak garis lurus tidak akan ditampilkan. Harus ditentukan 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 United Kingdom adalah "uk" (.co.uk) sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "The United Kingdom of Great Britain and Northern Ireland").
Saran juga dibobotkan berdasarkan kode wilayah. Google merekomendasikan untuk menetapkan
regionCode sesuai dengan preferensi regional pengguna.
Jika Anda menentukan kode wilayah yang tidak valid, API akan menampilkan error INVALID_ARGUMENT. Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.
Saat Anda menetapkan regionCode, prediksi di dalam wilayah tersebut mungkin
menghilangkan nama negara dari teks saran, yang berarti
structuredFormat.secondaryText
mungkin tidak ada. Oleh karena itu, pastikan aplikasi Anda menangani kasus saat
secondaryText tidak ditentukan atau tidak ada.
sessionToken
Token sesi adalah string yang dibuat pengguna yang melacak panggilan Autocomplete (New) sebagai "sesi". Autocomplete (New) menggunakan token sesi untuk mengelompokkan fase kueri dan pemilihan dari penelusuran pelengkapan otomatis pengguna ke dalam sesi terpisah untuk tujuan penagihan. Untuk mengetahui informasi selengkapnya, lihat Token sesi.
Memilih parameter untuk membiaskan hasil
Parameter Autocomplete (New) dapat memengaruhi hasil penelusuran secara berbeda. Tabel berikut memberikan rekomendasi penggunaan parameter berdasarkan hasil yang diinginkan.| Parameter | Rekomendasi penggunaan |
|---|---|
regionCode
|
Ditetapkan sesuai dengan preferensi regional pengguna. |
includedRegionCodes
|
Ditetapkan untuk membatasi hasil ke daftar wilayah yang ditentukan. |
locationBias
|
Gunakan jika hasil lebih disukai di dalam atau di sekitar wilayah. Jika berlaku, tentukan wilayah sebagai area pandang peta yang dilihat pengguna. |
locationRestriction
|
Gunakan hanya jika hasil di luar wilayah tidak boleh ditampilkan. |
origin
|
Gunakan jika jarak garis lurus ke setiap prediksi diinginkan. |
Contoh Autocomplete (New)
Membatasi penelusuran ke area tertentu menggunakan locationRestriction
locationRestriction menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak akan ditampilkan. Dalam 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": "Art museum",
"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/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "establishment", "museum", "point_of_interest" ] } }, { "placePrediction": { "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w", "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w", "text": { "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA", "matches": [ { "endOffset": 15 } ] }, "structuredFormat": { "mainText": { "text": "de Young Museum", "matches": [ { "endOffset": 15 } ] }, "secondaryText": { "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "tourist_attraction", "museum" ] } }, /.../ ] }
Anda juga dapat menggunakan locationRestriction untuk membatasi penelusuran ke Area pandang
persegi panjang. Contoh berikut membatasi permintaan ke pusat kota San
Francisco:
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Hasilnya terdapat dalam array suggestions:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "museum", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc", "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc", "text": { "text": "International Art Museum of America, Market Street, San Francisco, CA, USA", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "structuredFormat": { "mainText": { "text": "International Art Museum of America", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "secondaryText": { "text": "Market Street, San Francisco, CA, USA" } }, "types": [ "museum", "point_of_interest", "tourist_attraction", "art_gallery", "establishment" ] } } ] }
Membias penelusuran ke area tertentu menggunakan locationBias
Dengan locationBias, lokasi berfungsi sebagai bias, yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan. Pada contoh berikut, Anda membiaskan permintaan ke pusat kota San
Francisco:
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 kini 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" ] } }, ... ] }
Anda juga dapat menggunakan locationBias untuk membiaskan penelusuran ke Area pandang
persegi panjang. Contoh berikut membatasi permintaan ke pusat kota San
Francisco:
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Meskipun hasil penelusuran dalam area pandang persegi panjang muncul dalam respons, beberapa hasil berada di luar batas yang ditentukan, karena pembiasan. Hasil juga 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": [ "point_of_interest", "store", "establishment" ] } }, { "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": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI", "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI", "text": { "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Hollywood Boulevard, Los Angeles, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, /.../ ] }
Menggunakan includedPrimaryTypes
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 disertakan dalam
respons.
Dalam contoh berikut, Anda menentukan string input
"Soccer" dan menggunakan parameter includedPrimaryTypes untuk membatasi
hasil ke tempat usaha jenis "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 mencakup
tempat usaha dengan 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 kini berisi prediksi tempat dan prediksi kueri
seperti yang ditunjukkan di atas dalam 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. Jika Anda menyertakan origin, Autocomplete (Baru)
akan menyertakan
kolom distanceMeters dalam respons yang berisi
jarak garis lurus dari origin ke tujuan. Contoh ini menetapkan origin 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
Respons kini 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 } } ] }
Menemukan bisnis yang akan dibuka pada masa mendatang
Contoh berikut menunjukkan permintaan Autocomplete (New) untuk bisnis yang akan dibuka di masa mendatang di New Meadows, Idaho:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"input": "Roberts Greenhouse and Tree Farm",
"includeFutureOpeningBusinesses": true,
"locationBias": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
}
}' \
"https://places.googleapis.com/v1/places:autocomplete"
Respons menyertakan detail tentang tempat, tetapi tidak menyertakan tanggal pembukaan.
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do", "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "text": { "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA", "matches": [ { "endOffset": 32 } ] }, "structuredFormat": { "mainText": { "text": "Roberts Greenhouse and Tree Farm", "matches": [ { "endOffset": 32 } ] }, "secondaryText": { "text": "McLain Street, New Meadows, ID, USA" } }, "types": [ "garden_center", "establishment", "service", "store", "point_of_interest" ] } } ] }
Jarak tidak ada dalam respons
Dalam kasus tertentu, distanceMeters tidak ada dalam isi respons, meskipun origin disertakan dalam permintaan. Hal ini dapat terjadi
dalam skenario berikut:
distanceMeterstidak disertakan untuk prediksiroute.distanceMeterstidak disertakan jika nilainya adalah0, yang merupakan kasus untuk prediksi yang berjarak kurang dari 1 meter dari lokasioriginyang disediakan.
Library klien yang mencoba membaca kolom distanceMeters
dari objek yang diuraikan akan menampilkan kolom dengan nilai 0. Untuk
menghindari menyesatkan pengguna, jangan menampilkan jarak nol kepada
pengguna.
Pengoptimalan Autocomplete (New)
Bagian ini menjelaskan praktik terbaik untuk membantu Anda memaksimalkan layanan Autocomplete (New).
Berikut ini beberapa pedoman umum:
- Cara tercepat untuk membuat antarmuka pengguna yang berfungsi baik adalah dengan menggunakan widget Autocomplete (New) Maps JavaScript API, widget Autocomplete (New) Places SDK for Android, atau widget Autocomplete (New) Places SDK for iOS.
- Pahami kolom data Autocomplete (New) yang penting sejak awal.
- Kolom pembiasan lokasi dan pembatasan lokasi bersifat opsional, tetapi dapat memberikan dampak signifikan terhadap performa pelengkapan otomatis.
- Gunakan penanganan error untuk memastikan aplikasi Anda terdegrasi secara halus jika API menampilkan error.
- Pastikan aplikasi Anda menanganinya jika tidak ada pilihan dan menawarkan cara kepada pengguna untuk melanjutkan.
Praktik terbaik pengoptimalan biaya
Pengoptimalan biaya dasar
Untuk mengoptimalkan biaya penggunaan layanan Autocomplete (New), gunakan field mask di widget Place Details (New) dan Autocomplete (New) agar hanya menampilkan kolom data Autocomplete (New) yang Anda perlukan.
Pengoptimalan biaya lanjutan
Pertimbangkan implementasi Autocomplete (New) yang terprogram untuk mengakses SKU: Autocomplete Request pricing dan meminta hasil Geocoding API tentang tempat yang dipilih, bukan Place Details (New). Harga per permintaan yang dipasangkan dengan Geocoding API lebih hemat biaya daripada harga per sesi (berbasis sesi) jika kondisi berikut terpenuhi:
- Jika Anda hanya memerlukan lintang dan bujur atau alamat tempat yang dipilih pengguna, Geocoding API akan mengirimkan informasi ini dengan biaya yang lebih murah daripada panggilan Place Details (New).
- Jika pengguna memilih prediksi pelengkapan otomatis dalam rata-rata empat permintaan prediksi Autocomplete (New) atau kurang, harga per permintaan dapat lebih hemat biaya daripada harga per sesi.
| Yang dibutuhkan aplikasi Anda | Rata-rata permintaan Autocomplete (Baru) sebelum pengguna memilih prediksi | Penerapan yang direkomendasikan |
|---|---|---|
| Detail tempat selain alamat dan lokasi, seperti nama tempat, status bisnis, atau jam buka | Berapa saja | Autocomplete (New) berbasis sesi dengan Place Details (New) |
| Hanya alamat dan lintang/bujur dari prediksi yang dipilih | Empat atau kurang | Autocomplete (New) per permintaan dengan Geocoding API |
| Hanya alamat dan lintang/bujur dari prediksi yang dipilih | Lebih dari empat | Autocomplete (New) berbasis sesi untuk aplikasi khusus alamat |
Geocoding API dapat menjadi opsi yang lebih hemat biaya daripada Place Details (New) untuk aplikasi Anda, bergantung pada performa penggunaan Autocomplete (New). Efisiensi Autocomplete (New) setiap aplikasi bervariasi bergantung pada apa yang dimasukkan oleh pengguna, tempat aplikasi digunakan, dan apakah praktik terbaik pengoptimalan performa telah diterapkan.
Untuk menemukan jumlah rata-rata permintaan untuk tabel, analisis rata-rata jumlah karakter yang diketik pengguna sebelum memilih prediksi Autocomplete (New) di aplikasi Anda.
Autocomplete (New) berbasis sesi dengan Place Details (New)
Gunakan Autocomplete (New) berbasis sesi dengan Place Details (New).
Karena aplikasi Anda memerlukan Place Details (New), seperti nama tempat, status bisnis,
atau jam buka, penerapan Autocomplete (New) Anda harus menggunakan token sesi
(secara terprogram atau terintegrasi ke dalam widget
JavaScript,
Android,
atau iOS)
per sesi ditambah SKU Places yang berlaku,
bergantung pada kolom data tempat yang Anda minta.1
Penerapan widget
Pengelolaan sesi secara otomatis terintegrasi ke dalam widget
JavaScript,
Android,
atau iOS
. Ini mencakup permintaan Autocomplete (New) dan permintaan Place Details (New)
pada prediksi yang dipilih. Pastikan untuk menentukan parameter fields untuk memastikan Anda hanya meminta kolom data Autocomplete (New) yang Anda butuhkan.
Penerapan terprogram
Gunakan
token sesi
dengan permintaan Autocomplete (New) Anda. Saat meminta Place Details (New) tentang prediksi yang dipilih, sertakan parameter berikut:
- ID tempat dari respons Autocomplete (New)
- Token sesi yang digunakan dalam permintaan Autocomplete (Baru)
- Parameter
fieldsyang menentukan kolom data Autocomplete (Baru) yang Anda perlukan
Autocomplete (New) per permintaan dengan Geocoding API
Terapkan Autocomplete (New) secara terprogram tanpa token sesi dan panggil Geocoding API di prediksi tempat yang dipilih.
Geocoding API memberikan alamat dan koordinat lintang/bujur.
Membuat empat permintaan Autocomplete Requests ditambah panggilan Geocoding API tentang prediksi tempat yang dipilih lebih murah daripada biaya per sesi Autocomplete (New) per sesi.1
Pertimbangkan untuk menerapkan praktik terbaik performa guna membantu pengguna mendapatkan prediksi yang mereka cari dengan lebih sedikit karakter.
Autocomplete (New) berbasis sesi untuk aplikasi khusus alamat
Gunakan Autocomplete (New) berbasis sesi dengan Place Details (New).
Karena rata-rata jumlah permintaan yang Anda perkirakan akan dibuat sebelum pengguna memilih
prediksi Autocomplete (New) melebihi biaya harga per sesi, implementasi
Autocomplete (New) Anda harus menggunakan token sesi untuk permintaan Autocomplete (New)
dan permintaan Place Details (New) terkait
per sesi.
1
Penerapan widget
Pengelolaan sesi secara otomatis terintegrasi ke dalam widget
JavaScript,
Android,
atau iOS. Ini mencakup permintaan Autocomplete (New) dan permintaan Place Details (New)
pada prediksi yang dipilih. Pastikan untuk menentukan parameter fields
untuk memastikan Anda hanya meminta kolom yang Anda butuhkan.
Penerapan terprogram
Gunakan
token sesi
dengan permintaan Autocomplete (New) Anda.
Saat meminta Place Details (New) tentang prediksi yang dipilih,
sertakan parameter berikut:
- ID tempat dari respons Autocomplete (New)
- Token sesi yang digunakan dalam permintaan Autocomplete (Baru)
- Parameter
fieldsyang menentukan kolom seperti alamat dan geometri
Pertimbangkan untuk menunda permintaan Autocomplete (New)
Anda dapat menggunakan strategi seperti menunda permintaan Autocomplete (New) hingga pengguna mengetik tiga atau empat karakter pertama, sehingga aplikasi Anda membuat lebih sedikit permintaan. Misalnya, membuat permintaan Autocomplete (New) untuk setiap karakter setelah pengguna mengetik karakter ketiga berarti jika pengguna mengetik tujuh karakter, lalu memilih prediksi yang Anda buat satu permintaan Geocoding API, total biayanya adalah untuk 4 Autocomplete (New) Per Permintaan + Geocoding.1
Jika permintaan yang tertunda dapat menghasilkan permintaan terprogram rata-rata di bawah empat, Anda dapat mengikuti panduan ini untuk penerapan Autocomplete (New) yang berperforma dengan Geocoding API. Perhatikan bahwa permintaan yang tertunda dapat dianggap sebagai latensi oleh pengguna yang mungkin berharap melihat prediksi dengan setiap karakter baru yang mereka ketik.
Pertimbangkan untuk menerapkan praktik terbaik performa guna membantu pengguna Anda mendapatkan prediksi yang mereka cari dengan lebih sedikit karakter.
-
Untuk mengetahui biaya, lihat daftar harga Google Maps Platform.
Praktik terbaik performa
Panduan berikut menjelaskan cara mengoptimalkan performa Autocomplete (New):
- Tambahkan pembatasan negara, pembiasan lokasi, dan (untuk penerapan terprogram) preferensi bahasa ke penerapan Autocomplete (New) Anda. Preferensi bahasa tidak diperlukan dengan widget karena widget tersebut memilih preferensi bahasa dari browser atau perangkat seluler pengguna.
- Jika Autocomplete (New) disertai sebuah peta, Anda dapat membiaskan lokasi berdasarkan area pandang peta.
- Jika pengguna tidak memilih salah satu prediksi Autocomplete (New), umumnya karena tidak satu pun prediksi tersebut yang merupakan alamat hasil yang diinginkan, Anda dapat menggunakan kembali input pengguna yang asli untuk mendapatkan hasil yang lebih relevan:
- Jika Anda mengharapkan pengguna hanya memasukkan informasi alamat, gunakan kembali input pengguna yang asli dalam panggilan ke Geocoding API.
- Jika Anda memperkirakan pengguna akan memasukkan kueri untuk tempat tertentu berdasarkan nama atau alamat, gunakan permintaan Place Details (New). Jika hasil hanya diharapkan di wilayah tertentu, gunakan pembiasan lokasi.
- Pengguna yang memasukkan alamat sub-premis, seperti alamat untuk unit atau apartemen tertentu dalam sebuah gedung. Misalnya, alamat Ceko "Stroupežnického 3191/17, Praha" akan menghasilkan prediksi parsial di Autocomplete (Baru).
- Pengguna memasukkan alamat dengan awalan segmen jalan seperti "23-30 29th St, Queens" di New York City atau "47-380 Kamehameha Hwy, Kaneohe" di pulau Kauai di Hawai'i.
Pembiasan lokasi
Biasakan hasil ke area yang ditentukan dengan meneruskan parameter location dan parameter radius. Tindakan ini akan menginstruksikan Autocomplete (New) untuk memprioritaskan menampilkan hasil
dalam area yang ditentukan. Hasil di luar area yang ditentukan mungkin tetap ditampilkan. Anda dapat menggunakan parameter includedRegionCodes untuk memfilter hasil agar hanya menampilkan tempat dalam negara yang ditentukan.
Pembatasan lokasi
Batasi hasil ke area yang ditentukan dengan meneruskan parameter locationRestriction.
Anda juga dapat membatasi hasil ke wilayah yang ditentukan oleh parameter location
dan radius, dengan menambahkan parameter
locationRestriction
. Tindakan ini akan menginstruksikan Autocomplete (Baru) untuk hanya menampilkan hasil dalam wilayah tersebut.
Cobalah!
APIs Explorer memungkinkan Anda membuat contoh permintaan sehingga Anda dapat memahami API dan opsi API.
Pilih ikon API api di sisi kanan halaman.
Edit parameter permintaan jika perlu.
Pilih tombol Execute. Dalam dialog, pilih akun yang ingin Anda gunakan untuk membuat permintaan.
Di panel APIs Explorer, pilih ikon layar penuh fullscreen untuk meluaskan jendela APIs Explorer.