Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Parameter permintaan

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

Places Aggregate 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: Menerapkan filter komprehensif untuk mendapatkan agregat yang akurat. Filter yang tersedia mencakup hal berikut:
- Area geografis (lingkaran, wilayah, atau poligon kustom)
- Jenis tempat
- Status operasional
- Tingkat harga
- Rentang rating

Parameter yang diperlukan

Bagian ini membahas parameter yang diperlukan saat mengirim permintaan ke Places Aggregate API. Setiap permintaan harus menyediakan 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 akurat dan presisi berdasarkan wilayah lingkaran yang Anda tentukan.

center:
- latLng: Garis lintang dan bujur pusat lingkaran. Garis lintang harus berupa angka antara -90, 90, inklusif. Garis 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 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 area yang sedikit berlebihan (hingga 2-3%) yang mewakili wilayah tersebut.

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 yang disengketakan adalah wilayah dengan batas yang bertentangan atau klaim teritorial oleh berbagai negara atau entity. 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 batas dan nama negara.

Untuk menentukan apakah ID tempat mewakili jenis tempat yang tidak didukung, teruskan ID tempat dalam permintaan Geocoding API. Respons mencakup 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 mencakup:

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

Area kustom

Menentukan area poligon kustom menggunakan koordinat garis lintang dan bujur.

Anda dapat mengunjungi https://geojson.io/ untuk menggambar poligon kustom dan memasukkan koordinat tersebut ke dalam permintaan. A 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 diizinkan untuk berpotongan, dan tepi dengan panjang 180 derajat tidak diizinkan (yaitu, verteks yang berdekatan tidak dapat menjadi 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 mengetahui daftar jenis tempat utama 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 informasi selengkapnya tentang filter jenis.

Catatan: Filter jenis otomatis menyertakan subjenis dari jenis yang ditentukan. Misalnya, jika Anda memfilter berdasarkan gym, hasilnya juga akan menyertakan tempat yang dikategorikan dalam subjenisnya, seperti yoga_studio.

Parameter opsional

Filter ini bersifat opsional:

operatingStatus: Menentukan status tempat yang akan disertakan atau dikecualikan. Setelan default adalah memfilter 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) akan ditampilkan.
ratingFilter: Menentukan rentang rating tempat. Setelan default adalah tidak ada pemfilteran (semua rating disertakan dalam hasil).

Status operasional

Dengan filter operatingStatus, Anda dapat memfilter berdasarkan Status Operasional 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 diberikan, Anda harus menentukan nilai status operasional 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 akan 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 berdasarkan tingkat harga tertentu.
Jika satu atau beberapa filter diberikan: Hanya tempat yang cocok dengan tingkat harga yang ditentukan yang akan ditampilkan.

Filter rating

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

minRating: Rating pengguna rata-rata minimum (antara 1,0 dan 5,0).
maxRating: Rating 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 sebagai lebih besar dari maxRating, error INVALID_ARGUMENT akan ditampilkan.