Halaman ini diterjemahkan oleh Cloud Translation API.

Pelengkapan Otomatis (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

Layanan Autocomplete (Baru) adalah layanan web yang menampilkan tempat prediksi dan prediksi kueri sebagai respons terhadap permintaan HTTP. Dalam permintaan, tentukan teks string penelusuran dan batas geografis yang mengontrol area penelusuran.

Layanan Autocomplete (Baru) dapat mencocokkan dengan kata lengkap dan substring input, me-resolve nama tempat, alamat, dan kode plus. Karena itu aplikasi dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi kueri dan tempat dengan cepat.

Respons dari Autocomplete (New) API dapat berisi dua jenis prediksi:

Prediksi tempat: Tempat, seperti bisnis, alamat, dan titik minat, berdasarkan string teks input dan area penelusuran yang ditentukan. Prediksi tempat adalah yang ditampilkan secara default.
Prediksi kueri: String kueri yang cocok dengan string teks input dan area penelusuran. Prediksi kueri tidak ditampilkan secara default. Gunakan includeQueryPredictions parameter permintaan untuk menambahkan prediksi kueri ke yang dihasilkan.

Misalnya, Anda memanggil API menggunakan string yang berisi sebagian input pengguna, "Sicilian piz", dengan area penelusuran terbatas untuk San Francisco, CA. Responsnya kemudian berisi sebuah daftar prediksi tempat yang cocok dengan string penelusuran dan area penelusuran, seperti restoran bernama "Sicilian Pizza Kitchen", bersama dengan detail tentang tempat tersebut.

Prediksi tempat yang ditampilkan didesain untuk ditampilkan kepada pengguna guna membantu mereka dalam memilih tempat yang diinginkan. Anda dapat membuat Place Details (Baru) untuk mendapatkan informasi lebih lanjut tentang prediksi tempat yang dikembalikan.

Respons juga dapat berisi daftar prediksi kueri yang cocok dengan string penelusuran dan area penelusuran, seperti "Sicilian Pizza & Pasta". Setiap prediksi kueri dalam mencakup kolom text yang berisi string penelusuran teks yang direkomendasikan. Gunakan yang sebagai input untuk Penelusuran Teks (Baru) untuk melakukan pencarian yang lebih rinci.

API Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat membiasakan diri dengan API dan Opsi API:

Cobalah!

Permintaan Autocomplete (Baru)

Permintaan Autocomplete (Baru) adalah permintaan POST HTTP ke URL di bentuknya:

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 mereka rasakan. Setiap tempat direpresentasikan oleh Kolom placePrediction dan setiap kueri direpresentasikan dengan kolom queryPrediction.
Kolom placePrediction berisi informasi mendetail tentang satu prediksi tempat, termasuk ID tempat dan deskripsi teks.
Kolom queryPrediction berisi informasi mendetail tentang satu prediksi kueri.

Catatan: Pelengkapan Otomatis (Baru) menampilkan lima total prediksi, baik sebagai placePredictions, queryPredictions, atau kombinasi keduanya, bergantung pada permintaan. Misalnya, jika permintaan memang includeQueryPredictions tidak ditetapkan, isi respons mencakup maksimal lima placePredictions. Jika permintaan menetapkan includeQueryPredictions, metode isi respons mencakup hingga lima prediksi dalam kombinasi placePredictions dan queryPredictions.

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-kata lengkap dan {i>substring<i}, nama tempat, alamat, dan plus code. Layanan Autocomplete (Baru) mengembalikan kandidat berdasarkan {i>string <i}ini dan mengurutkan hasil berdasarkan relevansi yang mereka rasakan.

Parameter opsional

includedPrimaryTypes

Suatu tempat hanya dapat memiliki satu jenis utama dari jenis yang tercantum di Tabel A atau Tabel B. Misalnya, jenis utamanya mungkin "mexican_restaurant" atau "steak_house".

Secara default, API menampilkan semua tempat berdasarkan parameter input, terlepas dari dari nilai jenis utama yang terkait dengan tempat. Batasi hasil dari jenis utama atau jenis utama 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 untuk 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.
Catatan: Parameter includedPrimaryTypes hanya berfungsi pada jenis utama tempat, tidak semua jenis yang terkait dengan tempat tersebut. Meskipun setiap tempat memiliki tipe utama, tidak setiap jenis utama didukung oleh Places API (Baru). Jenis yang didukung termasuk yang tercantum dalam Tabel A atau Tabel B.
includeQueryPredictions

Jika true, responsnya mencakup prediksi tempat dan kueri. Default nilainya adalah false, yang berarti responsnya hanya mencakup prediksi tempat.
includedRegionCodes

Hanya sertakan hasil dari daftar region yang ditentukan, yang ditentukan sebagai array hingga 15 region ccTLD ("domain level teratas") nilai yang sama dengan dua karakter. 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 berada di area perpotongan dari dua pengaturan.
inputOffset

Offset karakter Unicode berbasis nol yang menunjukkan posisi kursor di input. Posisi kursor dapat memengaruhi prediksi yang ditampilkan. Jika kosong, defaultnya adalah panjang input.

Catatan: Dalam rilis Pratinjau Pribadi awal, fitur ini properti bernama predictionTermOffset.
languageCode

Bahasa pilihan untuk menampilkan hasil. Hasilnya mungkin dalam bahasa campuran jika bahasa yang digunakan dalam input berbeda dengan nilai yang ditentukan oleh languageCode, atau jika tempat yang dikembalikan tidak memiliki terjemahan dari bahasa bahasa lokal ke languageCode.
- Anda harus menggunakan IETF Kode bahasa BCP-47 untuk menentukan bahasa pilihan.
- Jika languageCode tidak diberikan, API akan menggunakan nilai yang ditetapkan dalam Header Accept-Language. Jika keduanya tidak ditentukan, defaultnya adalah en. Jika Anda menetapkan kode bahasa yang tidak valid, API akan menampilkan INVALID_ARGUMENT error.
- Bahasa pilihan memiliki pengaruh kecil pada serangkaian hasil yang API memilih untuk dikembalikan, dan urutan pengembaliannya. Hal ini juga memengaruhi kemampuan API untuk mengoreksi kesalahan ejaan.
- API berupaya menyediakan alamat yang dapat dibaca oleh pengguna dan populasi lokal, sementara pada saat yang sama mencerminkan input pengguna. Prediksi tempat adalah diformat berbeda tergantung masukan pengguna dalam setiap permintaan.
  - Istilah yang cocok dalam parameter input dipilih terlebih dahulu, menggunakan nama yang diselaraskan dengan preferensi bahasa yang ditunjukkan oleh parameter languageCode saat tersedia, dan sebaliknya menggunakan nama yang paling cocok dengan {i>input<i} 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 dikembalikan dalam bahasa pilihan, setelah istilah yang cocok memiliki dipilih agar cocok dengan istilah dalam parameter input. Jika nama bukan yang tersedia dalam bahasa pilihan, API akan menggunakan kecocokan terdekat.
locationBias atau locationRestriction

Anda dapat menentukan locationBias atau locationRestriction, namun tidak keduanya, untuk mendefinisikan area pencarian. Anggap locationRestriction sebagai menentukan wilayah tempat hasil harus berada, dan locationBias sebagai yang menetapkan wilayah di mana hasilnya harus dekat tetapi bisa berada di luar area tersebut.

Catatan: Jika Anda menghilangkan locationBias dan locationRestriction, maka API tersebut akan menggunakan pembiasan IP secara default. Dengan pembiasan IP, API menggunakan alamat IP perangkat untuk mencondongkan hasilnya.
- 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 dikembalikan.
Tentukan region locationBias atau locationRestriction sebagai {i>Viewport<i} persegi panjang atau sebagai lingkaran.
- Lingkaran ditentukan dengan titik pusat dan jari-jari dalam meter. Radius harus berada 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 akan menampilkan tidak ada hasil.
  
  Contoh:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- Persegi panjang adalah area pandang garis lintang dan garis bujur, yang direpresentasikan sebagai dua diagonal berlawanan dengan low dan titik tinggi. Sebuah area pandang dianggap sebagai wilayah tertutup, yang berarti wilayah itu mencakup perbatasannya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat, termasuk:
  - 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 dan high.longitude = 180 derajat, area pandang mencakup semua garis bujur.
  - Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur kosong.
  Baik low maupun high harus diisi, dan kotak yang ditampilkan wajib diisi. 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
    }
  }
}
```
asal

Titik asal untuk menghitung jarak garis lurus ke tujuan (ditampilkan sebagai distanceMeters). Jika nilai ini dihilangkan, jarak garis lurus tidak akan dikembalikan. 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 ccTLD ("domain level teratas") nilai yang sama dengan dua karakter. 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 INVALID_ARGUMENT {i>error<i}. Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.
sessionToken

Token sesi adalah string buatan pengguna yang melacak Autocomplete Panggilan (Baru) sebagai "sesi". Pelengkapan Otomatis (Baru) menggunakan token sesi untuk mengelompokkan fase kueri dan pemilihan dari penelusuran pelengkapan otomatis pengguna ke dalam sesi terpisah untuk 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 atribut Alamat IP perangkat untuk mencondongkan hasilnya. Anda dapat secara opsional menggunakan locationRestriction atau locationBias, namun tidak keduanya, untuk menentukan area yang akan ditelusuri.

locationRestriction menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak dikembalikan. 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 berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan. Dalam misalnya, 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 yang ditentukan nilai jenis utama untuk disertakan dalam respons.

Pada contoh berikut, Anda menentukan string input dari "Sepak bola" dan gunakan parameter includedPrimaryTypes untuk membatasi hasil pendirian 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 pendirian jenis yang tidak Anda inginkan, seperti "athletic_field".

Meminta prediksi kueri

Prediksi kueri tidak ditampilkan secara default. Menggunakan includeQueryPredictions parameter permintaan 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 Penelusuran Teks (Baru) untuk mendapatkan informasi lebih lanjut tentang salah satu prediksi kueri yang dikembalikan.

Catatan: Prediksi kueri tidak ditampilkan jika Parameter includedRegionCodes telah ditetapkan.

Gunakan origin

Dalam contoh ini, sertakan origin dalam permintaan sebagai koordinat lintang dan bujur. Saat Anda menyertakan origin, API akan menyertakan kolom distanceMeters di bagian 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 bisa membiasakan diri dengan API dan opsi API.

Pilih ikon API, , di sisi kanan halaman.
(Opsional) Memperluas Tampilkan parameter standar dan atur parameter fields ke mask kolom.
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.

Pelengkapan Otomatis (Baru)

Permintaan Autocomplete (Baru)

Tentang respons

Parameter wajib

input

Parameter opsional

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias atau locationRestriction

locationBias

locationRestriction

asal

regionCode

sessionToken

Contoh Autocomplete (Baru)

Menggunakan locationRestriction dan locationBias

Menggunakan includePrimaryTypes

Meminta prediksi kueri

Gunakan origin

Cobalah!