Parameter permintaan

Dokumen ini menjelaskan parameter permintaan untuk Places Insights API dan menyertakan insight serta praktik terbaik untuk menggunakan layanan ini.

Places Insights API memungkinkan Anda melakukan beberapa fungsi utama:

• Menghitung tempat: Menentukan jumlah tempat yang cocok dengan kriteria tertentu, seperti jenis lokasi, status operasional, tingkat harga, dan rating.
• Mengambil detail tempat: Mendapatkan nama tempat yang memenuhi filter yang ditentukan, lalu mengambil informasi yang lebih mendetail menggunakan Places API.
• Pemfilteran fleksibel: Terapkan filter komprehensif untuk mendapatkan insight yang akurat. Filter yang tersedia meliputi:
  • Area geografis (lingkaran, wilayah, atau poligon kustom)
  • Jenis tempat
  • Status operasional
  • Tingkat harga
  • Rentang rating

Parameter wajib

Bagian ini membahas parameter yang diperlukan saat membuat permintaan ke Places Insights API. Setiap permintaan harus menyediakan hal berikut:

• Jenis insight.
• Filter lokasi dan filter jenis.

Jenis insight

Menentukan jenis insight yang ingin dihitung. Jenis insight berikut didukung:

• INSIGHT_COUNT: Menampilkan jumlah tempat yang cocok dengan kriteria filter.
• INSIGHT_PLACES: Menampilkan ID tempat yang cocok dengan kriteria filter.

Catatan: Jika Anda memilih INSIGHT_PLACES, Places Insights API hanya menampilkan ID tempat jika count adalah 100 atau kurang.

Filter

Menentukan kriteria untuk memfilter tempat. Minimal, Anda harus menentukan LocationFilter dan TypeFilter.

Filter lokasi

Filter lokasi dapat memiliki salah satu jenis berikut:

• circle: Menentukan area sebagai lingkaran dengan pusat dan radius.
• region: Menentukan area sebagai region.
• customArea: Menentukan area sebagai poligon kustom.

Penting: Area untuk filter lokasi apa pun harus antara 1.556,86 meter persegi (kira-kira seukuran blok kota kecil) dan 2 triliun meter persegi (kira-kira seukuran Alaska). Permintaan dengan area di luar rentang ini akan menampilkan error INVALID_ARGUMENT.

Catatan: Untuk entitas dengan batas poligon yang ditentukan seperti taman atau bandara, entitas dianggap berada dalam area penelusuran jika ada bagian dari poligonnya yang berpotongan dengan area penelusuran yang ditentukan (lingkaran, wilayah, atau poligon kustom). Titik tengah entity tidak harus berada dalam area penelusuran.

Lingkaran

Jika memilih area geografis sebagai lingkaran, Anda harus memberikan center dan radius. center dapat berupa lintang dan bujur, atau ID Tempat dari pusat lingkaran. Metode ini memungkinkan pemfilteran yang tepat dan akurat berdasarkan wilayah melingkar yang Anda tentukan.

• center:
  • latLng: Lintang dan bujur pusat lingkaran. Lintang harus berupa angka antara -90, 90, inklusif. Bujur harus berupa angka antara -180, 180, inklusif.
  • place: ID tempat pusat lingkaran. Perhatikan bahwa hanya tempat titik yang didukung. String ini harus diawali dengan awalan places/.
• radius: Radius lingkaran dalam meter. Angka ini harus positif.

Wilayah

Tentukan area Anda sebagai wilayah dengan meneruskan ID tempat ke parameter place. ID tempat mewakili area geografis (seperti area yang dapat direpresentasikan oleh poligon). Misalnya, ID tempat Tampa, FL adalah places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Perhatikan bahwa tidak semua ID tempat memiliki geometri yang ditentukan dengan baik dan dalam hal ini, Places Insights API menampilkan kode error 400 dengan pesan yang menunjukkan bahwa wilayah tidak didukung. Selain itu, untuk wilayah geografis yang kompleks, pengoptimalan pemrosesan internal dapat menyebabkan sedikit kelebihan perkiraan area (hingga 2-3%) yang mewakili wilayah.

Penting: Saat menggunakan filter region dengan jenis insight INSIGHT_PLACES, permintaan yang menyertakan area yang disengketakan akan otomatis ditolak untuk memastikan akurasi dan netralitas layanan Google. Area sengketa adalah wilayah dengan klaim teritorial atau batas yang bertentangan oleh negara atau entitas yang berbeda. Batas yang disengketakan ditampilkan sebagai garis abu-abu putus-putus di Google Maps.

Untuk mengetahui informasi selengkapnya tentang cara mengidentifikasi wilayah yang disengketakan, lihat Memahami perbatasan dan nama negara.

Penting: Google tidak mendukung ID tempat tertentu yang termasuk dalam jenis wilayah berikut:

• Jenis region yang sangat besar sehingga menyebabkan latensi tinggi.
• Jenis wilayah yang sangat kecil sehingga membahayakan kepatuhan privasi.

Untuk menentukan apakah ID tempat mewakili jenis tempat yang tidak didukung, teruskan ID tempat dalam permintaan Geocoding API. Respons menyertakan array type yang mencantumkan jenis tempat yang terkait dengan ID tempat, seperti city, neighborhood, atau country.

Jenis tempat yang tidak didukung meliputi:

• establishment: biasanya menunjukkan tempat yang belum dikategorikan.
• street_number: menunjukkan nomor jalan yang akurat.
• floor: menunjukkan lantai alamat gedung.
• post_box: menunjukkan kotak pos tertentu.
• street_address: menunjukkan alamat yang akurat.
• room: menunjukkan ruang pada alamat gedung.
• intersection: menunjukkan persimpangan utama, biasanya persimpangan dua jalan utama.
• landmark: menunjukkan tempat terdekat yang digunakan sebagai referensi, untuk membantu navigasi.
• subpremise: menunjukkan entity yang dapat dialamatkan di bawah tingkat premis, seperti apartemen, unit, atau suite.
• sublocality_level_5: tingkat terperinci paling spesifik dari komponen alamat sublokalitas. biasanya mewakili subdivisi lingkungan yang sangat kecil atau area hiperlokal dalam kota.

Area kustom

Menentukan area poligon kustom menggunakan koordinat lintang dan bujur.

Penting: Koordinat yang menentukan vertex poligon harus dicantumkan dalam urutan berlawanan arah jarum jam. Hal ini mengikuti konvensi standar industri untuk menentukan poligon, dengan urutan berlawanan arah jarum jam menunjukkan bagian dalam poligon berada di sebelah kiri tepi batas.

Penting: Area kustom harus memiliki 7.000 vertex atau kurang.

Anda dapat membuka https://geojson.io/ untuk menggambar poligon kustom dan memasukkan koordinat tersebut ke dalam permintaan. Poligon harus memiliki minimal 4 koordinat, dengan koordinat pertama dan terakhir identik. Setidaknya 3 koordinat yang diberikan harus unik.

Koordinat yang identik secara berurutan akan diperlakukan sebagai satu koordinat. Namun, koordinat duplikat yang tidak berurutan (selain koordinat pertama dan terakhir yang diperlukan) akan menyebabkan error.

Selain itu, tepi yang tidak berdekatan tidak diizinkan untuk bersimpangan, dan tepi dengan panjang 180 derajat tidak diizinkan (yaitu, vertex yang berdekatan tidak boleh antipodal).

Contoh:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

Filter jenis

Menentukan jenis tempat yang akan disertakan atau dikecualikan. Untuk daftar jenis tempat primer dan sekunder yang didukung Places Insights API, lihat Tabel A di bagian Jenis Tempat untuk Places API (Baru). Anda harus menentukan setidaknya satu jenis includedTypes atau includedPrimaryTypes.

• includedTypes: Daftar jenis tempat yang disertakan.
• excludedTypes: Daftar jenis tempat yang dikecualikan.
• includedPrimaryTypes: Daftar jenis tempat utama yang disertakan.
• excludedPrimaryTypes: Daftar jenis tempat utama yang dikecualikan.

Untuk mempelajari lebih lanjut cara kerja filter jenis dan jenis tempat, lihat selengkapnya tentang filter jenis.

Parameter opsional

Filter ini bersifat opsional:

• operatingStatus: Menentukan status tempat yang akan disertakan atau dikecualikan. Setelan defaultnya adalah pemfilteran menurut operatingStatus: OPERATING_STATUS_OPERATIONAL (satu nilai tertentu).
• priceLevels: Menentukan tingkat harga tempat. Secara default, tidak ada pemfilteran (semua tingkat harga disertakan dalam hasil).
• ratingFilter: Menentukan rentang rating tempat. Setelan defaultnya adalah tidak ada pemfilteran (semua rating disertakan dalam hasil).

Status operasional

Dengan filter operatingStatus, Anda dapat memfilter berdasarkan Status Operasional (seperti beroperasi atau tutup sementara). Jika filter operatingStatus tidak ditetapkan, hanya tempat dengan status operasi OPERATING_STATUS_OPERATIONAL yang disertakan dalam hasil.

Tingkat harga

Dengan filter price_levels, Anda dapat memfilter berdasarkan Tingkat Harga (seperti gratis, sedang, atau mahal). Jika filter price_levels tidak ditetapkan, semua tingkat harga akan disertakan dalam hasil.

Filter rating

Memfilter tempat berdasarkan rating pengguna rata-ratanya. Kedua kolom ini bersifat opsional, sehingga jika dihilangkan, kolom ini akan secara default menyertakan tempat yang tidak memiliki rating.

• minRating: Peringkat pengguna rata-rata minimum (antara 1,0 dan 5,0).
• maxRating: Peringkat pengguna rata-rata maksimum (antara 1,0 dan 5,0).

Selain itu, nilai minRating harus selalu kurang dari atau sama dengan nilai maxRating. Jika minRating ditentukan lebih besar dari maxRating, error INVALID_ARGUMENT akan ditampilkan.