Places Aggregate API, yang sebelumnya dikenal sebagai Places Insights API, kini tersedia secara umum (GA).

Halaman ini diterjemahkan oleh Cloud Translation API.

Parameter permintaan

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

Places Aggregate API memungkinkan Anda melakukan beberapa fungsi utama:

Menghitung tempat: Tentukan jumlah tempat yang cocok dengan kriteria tertentu, seperti jenis lokasi, status operasional, tingkat harga, dan rating.
Mengambil detail tempat: Dapatkan nama tempat yang memenuhi filter yang ditentukan, lalu ambil informasi yang lebih mendetail menggunakan Places API.
Pemfilteran fleksibel: Terapkan filter komprehensif untuk mendapatkan agregat 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 mengirim permintaan ke Places Aggregate API. Setiap permintaan harus memberikan hal berikut:

Jenis insight.
Filter lokasi dan filter jenis.

Jenis insight

Menentukan jenis insight yang ingin Anda hitung. Jenis insight berikut didukung:

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

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 wilayah.
customArea: Menentukan area sebagai poligon kustom.

Lingkaran

Jika Anda memilih area geografis sebagai lingkaran, Anda harus memberikan center dan radius. center dapat berupa garis lintang dan bujur, atau ID Tempat dari pusat lingkaran. Metode ini memungkinkan pemfilteran yang tepat dan akurat berdasarkan wilayah lingkaran 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 dimulai 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 merepresentasikan 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 terdefinisi dengan baik dan dalam kasus ini, Places Aggregate API menampilkan kode error 400 dengan pesan yang menunjukkan bahwa wilayah tersebut tidak didukung. Selain itu, untuk wilayah geografis yang kompleks, pengoptimalan pemrosesan internal dapat menyebabkan perkiraan berlebih yang sedikit (hingga 2-3%) pada area yang merepresentasikan wilayah.

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

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

Untuk menentukan apakah ID tempat merepresentasikan 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 locality, neighborhood, atau country. Tempat akan ditolak untuk pemfilteran wilayah jika salah satu jenisnya cocok dengan daftar ini.

Jenis tempat yang tidak didukung meliputi:

establishment: biasanya menunjukkan tempat yang belum dikategorikan.
intersection: menunjukkan persimpangan utama, biasanya persimpangan dua jalan utama.
subpremise: menunjukkan entitas yang dapat dialamatkan di bawah tingkat lokasi, seperti apartemen, unit, atau suite.

Area kustom

Menentukan area poligon kustom menggunakan koordinat lintang dan bujur.

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 identik dan diperlukan) akan menghasilkan error.

Selain itu, tepi yang tidak berdekatan tidak boleh berpotongan, dan tepi dengan panjang 180 derajat tidak diizinkan (yaitu, verteks yang berdekatan tidak boleh berlawanan).

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 mengetahui daftar jenis tempat primer dan sekunder yang didukung Places Aggregate 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. Secara default, pemfilteran dilakukan berdasarkan operatingStatus: OPERATING_STATUS_OPERATIONAL (satu nilai tertentu).
priceLevels: Menentukan tingkat harga tempat yang akan disertakan. Secara default, tidak ada pemfilteran tingkat harga yang diterapkan, dan semua tempat (termasuk tempat tanpa informasi tingkat harga) ditampilkan.
ratingFilter: Menentukan rentang rating tempat. Defaultnya adalah tidak ada pemfilteran (semua rating disertakan dalam hasil).

Status operasional

Dengan filter operatingStatus, Anda dapat memfilter berdasarkan Status Operasi seperti OPERATIONAL atau TEMPORARILY_CLOSED. Perilaku filter operatingStatus berfungsi sebagai berikut:

Jika tidak ada filter yang diberikan, hanya tempat dengan status operasional OPERATING_STATUS_OPERATIONAL yang disertakan dalam hasil.
Jika satu atau beberapa filter disediakan, Anda harus menentukan nilai status operasi yang valid (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED, atau OPERATING_STATUS_TEMPORARILY_CLOSED).

Tingkat harga

Dengan filter priceLevels, Anda dapat memfilter tempat berdasarkan Tingkat Harga. Nilai tingkat harga yang valid adalah: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE, dan PRICE_LEVEL_VERY_EXPENSIVE.

Perilaku filter priceLevels adalah sebagai berikut:

Jika tidak ada filter yang diberikan: Semua tempat ditampilkan, terlepas dari apakah tempat tersebut memiliki tingkat harga yang ditetapkan. Hal ini mencakup tempat tanpa informasi tingkat harga, yang mungkin tidak ditampilkan saat memfilter menurut tingkat harga tertentu.
Jika satu atau beberapa filter disediakan: Hanya tempat yang cocok dengan tingkat harga yang ditentukan yang ditampilkan.

Filter rating

Memfilter tempat berdasarkan rating pengguna rata-rata. Kedua kolom ini bersifat opsional. Jika tidak diisi, 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.