Method: places.autocomplete

Menampilkan prediksi untuk input yang diberikan.

Permintaan HTTP

POST https://places.googleapis.com/v1/places:autocomplete

URL menggunakan sintaksis gRPC Transcoding.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Representasi JSON
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string
}
Kolom
input

string

Wajib. String teks yang akan ditelusuri.

locationBias

object (LocationBias)

Opsional. Membiaskan hasil ke lokasi yang ditentukan.

Maksimal satu dari locationBias atau locationRestriction harus ditetapkan. Jika keduanya tidak ditetapkan, hasilnya akan dibiaskan oleh alamat IP, yang berarti alamat IP akan dipetakan ke lokasi yang tidak akurat dan digunakan sebagai sinyal pembiasan.

locationRestriction

object (LocationRestriction)

Opsional. Membatasi hasil ke lokasi tertentu.

Maksimal satu dari locationBias atau locationRestriction harus ditetapkan. Jika keduanya tidak ditetapkan, hasilnya akan dibiaskan oleh alamat IP, yang berarti alamat IP akan dipetakan ke lokasi yang tidak akurat dan digunakan sebagai sinyal pembiasan.

includedPrimaryTypes[]

string

Opsional. Menyertakan jenis Tempat utama (misalnya, "restaurant" atau "gas_station") dari Tabel A atau Tabel B di Jenis Tempat (https://developers.google.com/maps/documentation/places/web-service/place-types), atau hanya (wilayah), atau hanya (kota). Tempat hanya ditampilkan jika jenis utama disertakan dalam daftar ini. Maksimal 5 nilai yang dapat ditentukan. Jika tidak ada jenis yang ditentukan, semua jenis Tempat akan ditampilkan.

includedRegionCodes[]

string

Opsional. Hanya sertakan hasil di wilayah yang ditentukan, yang ditetapkan sebagai maksimum 15 kode wilayah dua karakter CLDR. Kumpulan kosong tidak akan membatasi hasil. Jika locationRestriction dan includedRegionCodes ditetapkan, hasilnya akan berada di area persimpangan.

languageCode

string

Opsional. Bahasa yang digunakan untuk menampilkan hasil. Nilai defaultnya adalah en-US. Hasilnya mungkin dalam bahasa campuran jika bahasa yang digunakan dalam input berbeda dengan languageCode atau jika Tempat yang ditampilkan tidak memiliki terjemahan dari bahasa lokal ke languageCode.

regionCode

string

Opsional. Kode wilayah, ditetapkan sebagai kode wilayah dua karakter CLDR. Hal ini memengaruhi pemformatan alamat, peringkat hasil, dan dapat memengaruhi hasil yang ditampilkan. Hal ini tidak membatasi hasil pada wilayah yang ditentukan. Untuk membatasi hasil ke suatu wilayah, gunakan region_code_restriction.

origin

object (LatLng)

Opsional. Titik asal untuk menghitung jarak geodesi ke tujuan (ditampilkan sebagai distanceMeters). Jika nilai ini dihilangkan, jarak geodesi tidak akan ditampilkan.

inputOffset

integer

Opsional. Offset karakter Unicode berbasis nol dari input yang menunjukkan posisi kursor di input. Posisi kursor dapat memengaruhi prediksi yang ditampilkan.

Jika kosong, panjang defaultnya adalah input.

includeQueryPredictions

boolean

Opsional. Jika benar, respons akan menyertakan prediksi Tempat dan kueri. Jika tidak, respons hanya akan menampilkan prediksi Tempat.

sessionToken

string

Opsional. String yang mengidentifikasi sesi Autocomplete untuk tujuan penagihan. Harus berupa string base64 aman untuk URL dan nama file dengan panjang maksimal 36 karakter ASCII. Jika tidak, error INVALID_ARGUMENT akan ditampilkan.

Sesi dimulai saat pengguna mulai mengetik kueri, dan berakhir saat mereka memilih tempat serta panggilan ke Place Details atau Address Validation dilakukan. Setiap sesi dapat memiliki beberapa kueri, yang diikuti dengan satu permintaan Place Details atau Validasi Alamat. Kredensial yang digunakan untuk setiap permintaan dalam sebuah sesi harus berasal dari project Konsol Google Cloud yang sama. Setelah sesi selesai, token tidak lagi valid; aplikasi Anda harus menghasilkan token baru untuk setiap sesi. Jika parameter sessionToken dihapus, atau jika Anda menggunakan kembali token sesi, sesi tersebut dikenai biaya seolah-olah tidak ada token sesi yang diberikan (setiap permintaan ditagih secara terpisah).

Sebaiknya ikuti panduan berikut:

  • Gunakan token sesi untuk semua panggilan Place Autocomplete.
  • Buat token baru untuk setiap sesi. Sebaiknya gunakan UUID versi 4.
  • Pastikan kredensial yang digunakan untuk semua permintaan Place Autocomplete, Place Details, dan Validasi Alamat dalam sebuah sesi adalah milik project Konsol Cloud yang sama.
  • Pastikan untuk meneruskan token sesi yang unik untuk setiap sesi baru. Jika Anda menggunakan token yang sama untuk lebih dari satu sesi, setiap permintaan akan ditagih satu per satu.

Isi respons

Protokol respons untuk places.Autocomplete.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Representasi JSON
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
Kolom
suggestions[]

object (Suggestion)

Berisi daftar saran, diurutkan dalam urutan relevansi menurun.

LocationBias

Wilayah yang akan ditelusuri. Hasilnya mungkin menjadi bias di sekitar wilayah yang ditentukan.

Representasi JSON
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Kolom

Kolom union type.

type hanya dapat berupa salah satu dari yang berikut:

rectangle

object (Viewport)

Area pandang yang ditentukan oleh sudut timur laut dan barat daya.

circle

object (Circle)

Lingkaran yang ditentukan dengan titik tengah dan radius.

LocationRestriction

Wilayah yang akan ditelusuri. Hasilnya akan dibatasi ke wilayah yang ditentukan.

Representasi JSON
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Kolom

Kolom union type.

type hanya dapat berupa salah satu dari yang berikut:

rectangle

object (Viewport)

Area pandang yang ditentukan oleh sudut timur laut dan barat daya.

circle

object (Circle)

Lingkaran yang ditentukan dengan titik tengah dan radius.

Saran

Hasil saran Autocomplete.

Representasi JSON
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
Kolom

Kolom union kind.

kind hanya dapat berupa salah satu dari yang berikut:

placePrediction

object (PlacePrediction)

Prediksi untuk Tempat.

queryPrediction

object (QueryPrediction)

Prediksi untuk kueri.

PlacePrediction

Hasil prediksi untuk prediksi Place Autocomplete.

Representasi JSON
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
Kolom
place

string

Nama resource untuk Tempat yang disarankan. Nama ini dapat digunakan di API lain yang menerima nama Tempat.

placeId

string

ID unik Tempat yang disarankan. ID ini dapat digunakan di API lain yang menerima ID Tempat.

text

object (FormattableText)

Berisi nama yang dapat dibaca manusia untuk hasil yang ditampilkan. Untuk hasil bisnis, biasanya ini adalah nama dan alamat bisnis.

text direkomendasikan bagi developer yang ingin menampilkan satu elemen UI. Developer yang ingin menampilkan dua elemen UI yang terpisah, tetapi saling terkait, dapat menggunakan structuredFormat. Ada dua cara berbeda untuk merepresentasikan prediksi Tempat. Pengguna tidak boleh mencoba mengurai structuredFormat menjadi text atau sebaliknya.

Teks ini mungkin berbeda dari displayName yang ditampilkan oleh places.get.

Mungkin dalam bahasa campuran jika permintaan input dan languageCode dalam bahasa yang berbeda atau jika Tempat tidak memiliki terjemahan dari bahasa lokal ke languageCode.

structuredFormat

object (StructuredFormat)

Perincian prediksi Tempat menjadi teks utama yang berisi nama Tempat dan teks sekunder yang berisi fitur disambiguasi tambahan (seperti kota atau wilayah).

structuredFormat direkomendasikan untuk developer yang ingin menampilkan dua elemen UI yang terpisah, tetapi terkait. Developer yang ingin menampilkan satu elemen UI dapat menggunakan text. Ada dua cara berbeda untuk merepresentasikan prediksi Tempat. Pengguna tidak boleh mencoba mengurai structuredFormat menjadi text atau sebaliknya.

types[]

string

Daftar jenis yang berlaku untuk Tempat ini dari Tabel A atau Tabel B di https://developers.google.com/maps/documentation/places/web-service/place-types.

Jenis adalah kategorisasi Tempat. Tempat dengan jenis bersama akan memiliki karakteristik yang serupa.

distanceMeters

integer

Panjang geodesi dalam meter dari origin jika origin ditentukan. Prediksi tertentu seperti rute mungkin tidak mengisi kolom ini.

FormattableText

Teks yang merepresentasikan prediksi Tempat atau kueri. Teks dapat digunakan sebagaimana adanya atau dalam formatnya.

Representasi JSON
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
Kolom
text

string

Teks yang dapat digunakan sebagaimana adanya atau diformat dengan matches.

matches[]

object (StringRange)

Daftar rentang string yang mengidentifikasi tempat permintaan input cocok di text. Rentang ini dapat digunakan untuk memformat bagian tertentu dari text. Substring mungkin tidak sama persis dengan input jika kecocokan tersebut ditentukan oleh kriteria selain pencocokan string (misalnya, koreksi ejaan atau transliterasi).

Nilai ini adalah offset karakter Unicode text. Rentang tersebut dijamin akan diurutkan dalam nilai offset yang meningkat.

StringRange

Mengidentifikasi substring dalam teks tertentu.

Representasi JSON
{
  "startOffset": integer,
  "endOffset": integer
}
Kolom
startOffset

integer

Offset berbasis nol dari karakter Unicode pertama pada string (inklusif).

endOffset

integer

Offset berbasis nol dari karakter Unicode terakhir (eksklusif).

StructuredFormat

Berisi perincian prediksi kueri atau Tempat ke dalam teks utama dan teks sekunder.

Untuk prediksi Tempat, teks utama berisi nama spesifik Tempat. Untuk prediksi kueri, teks utama berisi kueri.

Teks sekunder berisi fitur disambiguasi tambahan (seperti kota atau wilayah) untuk mengidentifikasi lebih lanjut Tempat atau menyaring kueri.

Representasi JSON
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
Kolom
mainText

object (FormattableText)

Menampilkan nama Tempat atau kueri.

secondaryText

object (FormattableText)

Menampilkan fitur disambiguasi tambahan (seperti kota atau wilayah) untuk mengidentifikasi lebih lanjut Tempat atau menyaring kueri.

QueryPrediction

Hasil prediksi untuk prediksi Query Autocomplete.

Representasi JSON
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
Kolom
text

object (FormattableText)

Teks yang diprediksi. Teks ini tidak mewakili Tempat, melainkan kueri teks yang dapat digunakan di endpoint penelusuran (misalnya, Text Search).

text direkomendasikan bagi developer yang ingin menampilkan satu elemen UI. Developer yang ingin menampilkan dua elemen UI yang terpisah, tetapi saling terkait, dapat menggunakan structuredFormat. Kedua cara tersebut berbeda untuk merepresentasikan prediksi kueri. Pengguna tidak boleh mencoba mengurai structuredFormat menjadi text atau sebaliknya.

Mungkin dalam bahasa campuran jika permintaan input dan languageCode menggunakan bahasa yang berbeda atau jika sebagian kueri tidak memiliki terjemahan dari bahasa lokal ke languageCode.

structuredFormat

object (StructuredFormat)

Perincian prediksi kueri menjadi teks utama yang berisi kueri dan teks sekunder yang berisi fitur pembeda tambahan (seperti kota atau wilayah).

structuredFormat direkomendasikan untuk developer yang ingin menampilkan dua elemen UI yang terpisah, tetapi terkait. Developer yang ingin menampilkan satu elemen UI dapat menggunakan text. Kedua cara tersebut berbeda untuk merepresentasikan prediksi kueri. Pengguna tidak boleh mencoba mengurai structuredFormat menjadi text atau sebaliknya.