Mulai menggunakan Places Insights

Fungsi Jumlah Tempat adalah kueri SQL yang telah ditentukan dan berjalan di BigQuery. Fungsi ini adalah cara yang direkomendasikan untuk membuat kueri set data Places Insights guna mengambil jumlah pasti dan ID Tempat. Meskipun Anda juga dapat membuat kueri set data secara langsung, kedua metode kueri ini menangani nilai minimum privasi dan area penelusuran:

• Fungsi Jumlah Tempat dapat menampilkan jumlah apa pun, termasuk 0, tetapi menerapkan area penelusuran minimum sebesar 40,0 meter x 40,0 meter (1.600 m²) (40,0 meter x 40,0 meter / 1.600 m²). Fungsi ini juga menampilkan ID Tempat, yang dapat digunakan untuk mencari informasi tentang Tempat tertentu, dan mendukung analisis POI historis di seluruh snapshot bulanan sebelumnya menggunakan filter tanggal opsional.

• Kueri set data tempat hanya dapat menampilkan jumlah 5 dan yang lebih tinggi (menghilangkan jumlah rendah 0–4 untuk menjaga privasi diferensial), tetapi tidak menerapkan batasan pada ukuran area penelusuran.

Kecuali jika Anda perlu melakukan analisis spasial yang kompleks, sebaiknya mulai dengan fungsi Jumlah Tempat seperti PLACES_COUNT_PER_H3. Fungsi ini memberikan insight kepadatan spasial langsung di seluruh sel petak standar, menampilkan ID Tempat untuk pemeriksaan kebenaran dasar, dan dibuat khusus untuk rekayasa fitur geospasial dan model ML.

Produk atau fitur ini ada dalam Pratinjau (pra-GA). Produk dan fitur pra-GA mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Penawaran Pra-GA tercakup dalam Persyaratan Khusus Layanan Google Maps Platform. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Memilih fungsi Jumlah Tempat yang optimal

Places Insights mendukung beberapa fungsi spasial. Untuk eksekusi kueri yang dioptimalkan, pemrosesan paralel, dan skalabilitas batch, sebaiknya gunakan fungsi berikut:

• PLACES_COUNT_PER_H3: Menampilkan tabel BigQuery berisi jumlah tempat per sel H3. Fungsi ini direkomendasikan untuk analisis kepadatan regional dan heatmapping choropleth.
• PLACES_COUNT_V2: Menampilkan tabel yang berisi jumlah tempat dan contoh ID Tempat. Fungsi ini menerima parameter tabel yang berisi geografi input Anda. Dengan meneruskan seluruh tabel secara langsung, mesin eksekusi BigQuery dapat mendistribusikan beban kerja dan memproses persimpangan spasial secara paralel, sehingga memungkinkan batch processing yang sangat efisien untuk analisis skala besar.
• PLACES_COUNT_PER_TYPE_V2: Menampilkan tabel berisi jumlah tempat dan contoh ID Tempat, yang dikategorikan menurut jenis tempat. Mirip dengan PLACES_COUNT_V2, meneruskan geografi input Anda sebagai parameter tabel memungkinkan BigQuery memparalelkan persimpangan spasial secara native di seluruh set data besar.
• PLACES_COUNT_CHANGE: Menampilkan tabel berisi jumlah tempat ditambah ID Tempat yang ditambahkan dan dihapus antara dua bulan tertentu. Mirip dengan PLACES_COUNT_V2, meneruskan geografi input Anda sebagai parameter tabel memungkinkan BigQuery memparalelkan persimpangan spasial secara native di seluruh set data besar.

Selain jumlah tempat, fungsi ini juga menampilkan hingga 250 ID Tempat per elemen respons.

ID Tempat dapat digunakan dengan:

• Places API (Baru)
• Geocoding API
• Places UI Kit

Catatan: Anda dapat mengakses fungsi Jumlah Tempat untuk kota dan negara yang sama dengan yang Anda akses.

Menjalankan kueri dengan fungsi Jumlah Tempat

Gunakan format berikut untuk memanggil fungsi: [project name (optional)].[table name].[function name].

Jika Anda mengubah nama set data tertaut saat menyiapkan Places Insights, gunakan nama kustom Anda, bukan nama tabel default. Anda juga dapat menyertakan nama project secara opsional. Jika tidak disertakan, kueri akan menggunakan project aktif secara default.

Contoh:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

Gunakan JSON_OBJECT untuk meneruskan argumen ke fungsi.

Catatan: Saat menggunakan fungsi Jumlah Tempat, tentukan fungsi dalam klausa FROM dan hapus WITH_AGGREGATION_THRESHOLD.

Memfilter hasil kueri menggunakan parameter yang peka huruf besar/kecil

Fungsi Jumlah Tempat mendukung banyak filter untuk menyempurnakan penelusuran Anda. Parameter ini (misalnya, price_level atau types) peka huruf besar/kecil dan harus cocok dengan nama parameter. Untuk mengetahui daftar lengkap opsi, lihat referensi parameter filter.

Membuat kueri snapshot historis dengan snapshot_date

Secara default, fungsi Jumlah Tempat membuat kueri snapshot data terbaru yang tersedia. Untuk menganalisis data tempat seperti yang ada selama bulan tertentu di masa lalu, tambahkan parameter snapshot_date opsional ke JSON_OBJECT Anda.

• Format: YYYY-MM (misalnya, '2026-07').
• Default: Jika dihilangkan, fungsi akan otomatis membuat kueri snapshot terbaru.

Contoh berikut membuat kueri jumlah restoran di sekitar area penelusuran Anda seperti yang tercatat dalam snapshot Juli 2026:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07' -- Optional historical snapshot month
  )
);

Pada contoh berikutnya, Anda akan menerapkan filter untuk membatasi penelusuran berdasarkan rating pengguna minimum, tingkat harga, status bisnis, dan apakah restoran mengizinkan, menggunakan fungsi PLACES_COUNT_V2.

Pertama, gunakan tabel geografi input Anda atau siapkan tabel dengan geografi yang dipilih:

Penting: Anda harus membuat set data yang berisi tabel geografi input di region yang sama dengan set data Places Insights tertaut. Jika lokasinya tidak cocok, BigQuery akan menampilkan error.

-- Create a table for the input geographies
CREATE TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas` AS (
  SELECT
    '1' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9857, 40.7484) AS geo -- Empire State Building
  UNION ALL
  SELECT
    '2' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9851, 40.7580) AS geo -- Times Square
);

Selanjutnya, panggil PLACES_COUNT_V2 dengan tabel dan objek JSON yang berisi filter. Radius penelusuran disertakan dalam filter JSON dan akan diterapkan di sekitar setiap titik dalam tabel my_search_areas.

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters around each point in 'geo'
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'min_rating', 1.3,
      'price_level', ['PRICE_LEVEL_INEXPENSIVE', 'PRICE_LEVEL_MODERATE'],
      'allows_dogs', TRUE
      )
);

Catatan: Sertakan filter business_status untuk memastikan Anda mendapatkan jumlah bisnis OPERATIONAL. Jika tidak, jumlah tersebut akan mencakup bisnis yang tutup.

Contoh: Membuat kueri jumlah restoran dan lokasi merek dengan PLACES_COUNT_V2

Contoh berikut menggunakan fungsi PLACES_COUNT_V2 dengan tabel geografi input kustom my_search_areas untuk menampilkan jumlah restoran yang beroperasi dalam jarak 1.000 meter dari Empire State Building dan Times Square di New York City pada Juli 2026:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07'
      )
);

Responsnya adalah tabel BigQuery yang berisi geo_id, geografi, jumlah, dan contoh ID Tempat.

Contoh berikut menggunakan fungsi PLACES_COUNT_V2 untuk memfilter berdasarkan ID merek tertentu. Dalam contoh ini, kita memfilter lokasi Starbucks menggunakan ID merek "1413758728321880760".

Untuk menemukan ID merek yang ingin Anda gunakan untuk memfilter, buat kueri brands tabel untuk set data Anda (misalnya, places_insights___us.brands). Untuk mengetahui informasi selengkapnya tentang set data merek, lihat Menulis kueri menggunakan data merek.

Misalnya, untuk menemukan ID merek "Starbucks":

SELECT id, name
FROM `PROJECT_NAME.places_insights___us.brands`
WHERE name = "Starbucks"

Setelah mendapatkan ID merek, Anda dapat menggunakannya dalam filter brand_ids seperti yang ditunjukkan dalam kueri berikut:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'brand_ids', ["1413758728321880760"]
      )
);

Catatan: Parameter wajib dan opsional berbeda untuk setiap fungsi Jumlah Tempat seperti yang dijelaskan dalam filter.

Memvisualisasikan output kueri dengan alat Google Cloud

Alat analisis dan business intelligence tools membantu Anda menemukan insight dari data BigQuery. BigQuery mendukung beberapa alat visualisasi data Google dan pihak ketiga yang dapat Anda gunakan untuk menganalisis hasil fungsi Anda pada data Places Insights.

Untuk contoh visualisasi hasil fungsi, lihat Memvisualisasikan hasil di dalam referensi PLACES_COUNT_PER_H3. Untuk mengetahui informasi selengkapnya tentang visualisasi hasil Places Insights, lihat Memvisualisasikan hasil kueri.

Batasan dan persyaratan fungsi

Fungsi Jumlah Tempat memiliki batasan dan persyaratan berikut:

• Fungsi ini hanya mendukung insight COUNT.
• Area penelusuran minimum sebesar 40,0 meter x 40,0 meter (1.600 m²) (40,0 meter x 40,0 meter / 1.600 m²) diperlukan.
• Batas Ukuran Input Parameter: Objek JSON yang diteruskan sebagai parameter ke fungsi dibatasi hingga 1 MB. Dampak batasan ini bergantung pada versi fungsi:
  • Untuk fungsi V2 (PLACES_COUNT_V2, PLACES_COUNT_PER_TYPE_V2, PLACES_COUNT_CHANGE), batasan ini hanya berlaku untuk objek JSON filter. Karena geografi disediakan secara terpisah menggunakan parameter tabel, fungsi ini dapat diskalakan ke jumlah geografi input yang jauh lebih besar tanpa mencapai batas ukuran JSON.
  • Untuk PLACES_COUNT_PER_H3, PLACES_COUNT, PLACES_COUNT_PER_TYPE, dan PLACES_COUNT_PER_GEO, batasan ini berlaku untuk seluruh objek JSON, termasuk semua definisi geografi. Hal ini dapat membatasi jumlah geografi yang dapat diproses dalam satu panggilan.
• Tidak ada dukungan untuk memfilter berdasarkan ID Tempat atau komponen alamat.
• Anda hanya dapat mengakses fungsi Jumlah Tempat untuk kota dan negara yang Anda langgani. Lihat Menyiapkan Places Insights untuk akses set data.
• Parameter filter (misalnya, geography atau types) peka huruf besar/kecil dan harus cocok dengan nama parameter, atau kueri akan gagal.