Halaman ini diterjemahkan oleh Cloud Translation API.

Pelengkapan Otomatis (Baru)

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 lengkap dan substring input, yang me-resolve nama tempat, alamat, dan Plus Codes. Oleh karena itu, aplikasi dapat mengirim kueri saat pengguna mengetik, untuk memberikan tempat secara real time dan prediksi kueri.

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 input pengguna sebagian, "Sicilian piz", dengan area penelusuran terbatas di San Francisco, CA, sebagai input. Responsnya kemudian akan berisi daftar prediksi tempat yang cocok dengan string penelusuran dan area penelusuran, seperti restoran bernama "Sicilian Pizza Kitchen", beserta detail tempat tersebut.

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

Responsnya 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 (New) untuk melakukan penelusuran yang lebih mendetail.

Permintaan Autocomplete (Baru)

Permintaan Autocomplete (Baru) 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

Membuat permintaan menggunakan Autocomplete (Baru)

Places API mendukung API Autocomplete dan Query Autocomplete yang ada. Jika Anda sudah terbiasa dengan API ini, versi Pratinjau Pelengkapan Otomatis (Baru) membuat perubahan berikut:

Autocomplete baru menggunakan permintaan POST HTTP. Teruskan parameter dalam isi permintaan atau di header sebagai bagian dari permintaan HTTP POST. Sebaliknya, dengan API yang ada, Anda meneruskan parameter URL menggunakan permintaan HTTP GET.
Autocomplete baru mendukung kunci API dan token OAuth sebagai mekanisme autentikasi.
Hanya JSON yang didukung sebagai format respons dalam Autocomplete baru.

Tabel berikut mencantumkan parameter dalam API Autocomplete dan Query Autocomplete yang ada yang telah diganti namanya atau diubah untuk Autocomplete baru, atau parameter yang tidak lagi didukung.

Parameter saat ini	Parameter baru	Catatan
`components`	`includedRegionCodes`
`language`	`languageCode`
`location`	`locationBias`
`ipbias`		Jika Anda menghilangkan `locationBias` dan `locationRestriction`, API akan menggunakan pembiasan IP secara default.
`offset`	`inputOffset`
`radius`	`locationBias` atau `locationRestriction`
`region`	`regionCode`
`stricbounds`	`locationRestriction`
`sessiontoken`	`sessionToken`
`types`	`includedPrimaryTypes`

Batas penggunaan

Selama rilis Pratinjau, terdapat batasan maksimum 600 kueri per menit per project yang dapat dibuat.

Opsi dukungan untuk rilis Pratinjau

Meskipun Google tidak berkewajiban untuk memberikan dukungan bagi versi, fitur, atau fungsi Layanan, kami akan mempertimbangkan permintaan pada tahap pengembangan ini secara kasus per kasus.

Versi pra-rilis tidak tercakup dalam SLA Google Maps Platform.
Penggunaan mekanisme penggantian direkomendasikan, terutama jika Anda menggunakan versi pra-rilis di lingkungan produksi. Beberapa contoh situasi penggantian adalah: kuota terlampaui, kode respons dan latensi yang tidak terduga, atau respons yang tidak terduga jika dibandingkan dengan Autocomplete yang ada.

Anda dapat menggunakan issue tracker untuk meminta fitur baru atau menyarankan modifikasi pada fitur yang ada. Harap jelaskan fungsi spesifik yang Anda inginkan ditambahkan, serta alasan yang menurut Anda penting. Jika memungkinkan, sertakan detail spesifik tentang kasus penggunaan Anda dan peluang baru yang akan dimungkinkan oleh fitur tersebut:

Untuk pertanyaan lain tentang fitur, silakan kirim email ke newplacesapi@google.com.

Tentang respons

Autocomplete (New) menampilkan objek JSON sebagai respons. Dalam respons:

Array suggestions berisi semua tempat dan kueri yang diprediksi secara berurutan berdasarkan relevansi yang dirasakan. Setiap tempat ditunjukkan oleh kolom placePrediction dan setiap kueri diwakili oleh kolom queryPrediction.
Kolom placePrediction berisi informasi mendetail tentang prediksi satu tempat, termasuk ID tempat dan deskripsi teks.
Kolom queryPrediction berisi informasi mendetail tentang satu prediksi kueri.

Catatan: Autocomplete (Baru) menampilkan total lima prediksi, baik sebagai placePredictions, queryPredictions, maupun kombinasi keduanya, bergantung pada permintaannya. Misalnya, jika permintaan tidak menetapkan includeQueryPredictions, isi respons akan menyertakan hingga lima placePredictions. Jika permintaan menetapkan includeQueryPredictions, isi respons akan menyertakan hingga lima prediksi dalam kombinasi placePredictions dan queryPredictions.

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 wajib

input

String teks yang digunakan untuk menelusuri. Tentukan kata dan substring lengkap, nama tempat, alamat, dan kode plus. Layanan Autocomplete (Baru) menampilkan kandidat kecocokan berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang dirasakan.

Parameter opsional

includedPrimaryTypes

Sebuah tempat hanya dapat memiliki satu jenis utama dari jenis Tabel A atau Tabel B yang terkait dengannya. Misalnya, jenis utamanya 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 ke jenis utama atau jenis primer 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 dapat disertakan dalam respons.

Permintaan ditolak dengan error INVALID_REQUEST jika:
- Lebih dari lima jenis ditentukan.
- Semua jenis yang tidak dikenal akan ditentukan.
includeQueryPredictions

Jika true, responsnya akan menyertakan prediksi tempat dan kueri. Nilai defaultnya adalah false, yang berarti responsnya hanya menyertakan prediksi tempat.
includedRegionCodes

Hanya sertakan hasil dari daftar region yang ditentukan, yang ditetapkan sebagai array 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 berada di area persimpangan kedua setelan.
inputOffset

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

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

Bahasa pilihan untuk menampilkan hasil. Hasilnya mungkin tersedia dalam bahasa campuran jika bahasa yang digunakan dalam input berbeda dari nilai yang ditentukan oleh languageCode, atau jika tempat yang ditampilkan tidak memiliki terjemahan dari bahasa lokal ke bahasa languageCode.
- Anda harus menggunakan kode bahasa IETF BCP-47 untuk menentukan bahasa pilihan.
- Jika languageCode tidak diberikan, API akan menggunakan nilai yang ditentukan dalam header Accept-Language. Jika keduanya tidak ditentukan, defaultnya adalah en. Jika Anda menentukan kode bahasa yang tidak valid, API akan menampilkan error INVALID_ARGUMENT.
- Bahasa yang dipilih berpengaruh kecil terhadap kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan tampilannya. Hal ini juga memengaruhi kemampuan API untuk memperbaiki kesalahan ejaan.
- API mencoba memberikan 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 dipilih terlebih dahulu, menggunakan nama yang selaras dengan preferensi bahasa yang ditunjukkan oleh parameter languageCode jika tersedia, sedangkan jika tidak, 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 lainnya 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 bahasa terdekat yang cocok.
locationBias atau locationRestriction

Anda dapat menentukan locationBias atau locationRestriction, tetapi tidak keduanya, untuk menentukan area penelusuran. Bayangkan locationRestriction sebagai menentukan wilayah tempat hasil harus berada, dan locationBias menentukan wilayah tempat hasil harus dekat, tetapi bisa saja di luar area tersebut.

Catatan: Jika Anda menghilangkan locationBias dan locationRestriction, API akan menggunakan pembiasan IP secara default. Dengan pembiasan IP, API menggunakan alamat IP perangkat untuk membiaskan 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 ditampilkan.
Tentukan wilayah locationBias atau locationRestriction sebagai Area Pandang persegi panjang atau lingkaran.
- Lingkaran ditentukan oleh titik tengah 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. Selain itu, permintaan tersebut 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 dengan low dan titik tinggi. Area pandang dianggap sebagai area tertutup, yang berarti area pandang tersebut menyertakan batasnya. Batas garis lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus memiliki rentang antara -180 hingga 180 derajat:
  - Jika low = high, area tampilan 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 dan high.longitude = 180 derajat, area pandang akan mencakup semua garis bujur.
  - Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur tersebut kosong.
  low dan high harus diisi, dan kotak yang diwakili tidak boleh kosong. Area pandang 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
    }
  }
}
```
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 lebih lanjut, lihat Token sesi.

Contoh Autocomplete (Baru)

Menggunakan locationRestriction dan locationBias

API menggunakan pembiasan IP secara default untuk mengontrol area penelusuran. Dengan pembiasan IP, API menggunakan alamat IP perangkat untuk membiaskan hasilnya. Anda dapat menggunakan locationRestriction atau locationBias secara opsional, 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 berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan. Dalam 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 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"
        ]
      }
    },
    ...
  ]
}

Menggunakan includePrimaryTypes

Gunakan parameter includedPrimaryTypes untuk membatasi hasil dari permintaan agar berjenis tertentu seperti yang tercantum dalam Tabel A dan Tabel B. Anda dapat menentukan array hingga lima nilai. Jika dihilangkan, semua jenis akan ditampilkan.

Pada contoh berikut, Anda menentukan string input "Sepak bola" dan menggunakan parameter includedPrimaryTypes untuk membatasi hasil ke tempat usaha 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 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 artikel 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.

Catatan: Prediksi kueri tidak ditampilkan jika parameter includedRegionCodes ditetapkan.

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 menetapkan 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
      }
    }
  ]
}

Pelengkapan Otomatis (Baru)

Permintaan Autocomplete (Baru)

Membuat permintaan menggunakan Autocomplete (Baru)

Batas penggunaan

Opsi dukungan untuk rilis Pratinjau

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