Esegui query sui conteggi dei PDI per H3

La funzione PLACES_COUNT_PER_H3 aggrega i dati dei punti d'interesse (PDI) in celle della griglia spaziale H3 standardizzate con una risoluzione specificata. Questa funzione è il percorso consigliato per l'analisi della densità regionale, la mappatura competitiva e la generazione di mappe termiche coropletiche esagonali.

Per chiamare la funzione PLACES_COUNT_PER_H3, utilizza una clausola SQL FROM perché la funzione restituisce una tabella.

Sintassi e parametri

SELECT * FROM `PROJECT_NAME.LINKED_DATASET_NAME.PLACES_COUNT_PER_H3`(
  filters
)

Parametri

• PROJECT_NAME: il nome del tuo progetto cloud Google. Se non specifichi un nome del progetto, la query verrà eseguita per impostazione predefinita sul progetto attivo.
• LINKED_DATASET_NAME: il nome del set di dati Places Insights a cui hai effettuato l'iscrizione (ad esempio places_insights___us).
• filters (JSON): un oggetto JSON creato utilizzando JSON_OBJECT contenente parametri di filtro coppia chiave-valore.

Filtri JSON obbligatori

• geography (GEOGRAPHY): l'area di ricerca di delimitazione (punto, stringa di linee o poligono) da indicizzare.
• h3_resolution (INTEGER): il livello di risoluzione della cella H3 (i valori supportati vanno da 0 a 11).

Filtri JSON facoltativi

• Parametri aggiuntivi come types, business_status, price_level e min_rating per filtrare i luoghi conteggiati all'interno di ogni cella. Consulta l'elenco completo dei parametri di filtro.

Schema della tabella di output

La funzione restituisce una tabella BigQuery con una riga per ogni indice di cella H3 che interseca la geometria di destinazione:

Nome colonna	Tipo di dati	Descrizione
h3_cell_index	STRING	L'identificatore univoco dell'indice H3 della cella.
geography	GEOGRAPHY	Un poligono che rappresenta il confine fisico della cella H3.
count	INTEGER	Il numero esatto totale di luoghi operativi corrispondenti all'interno di questa specifica cella H3 o zero se non corrispondono luoghi.
sample_place_ids	ARRAY<STRING>	Un array di un massimo di 250 ID luogo situati all'interno di questa cella, che consente query dirette sui dati di fatto utilizzando l'API Places.

Aggrega la densità dei PDI regionali utilizzando PLACES_COUNT_PER_H3

La funzione elabora l'area geografica di delimitazione specificata nei filtri, identifica tutti gli esagoni H3 che si intersecano alla risoluzione target e restituisce i conteggi esatti dei luoghi e gli ID luogo per ogni esagono.

Esempio: conta i negozi di alimentari e i minimarket accessibili in sedia a rotelle nello stato di New York

Questa query aggrega i minimarket e i negozi di alimentari operativi e accessibili in sedia a rotelle nello stato di New York utilizzando un livello di risoluzione H3 pari a 8. La geometria dei confini dello stato di New York viene interrogata dinamicamente dal set di dati pubblico bigquery-public-data.geo_us_boundaries.states.

-- Query POI count per H3 cell intersecting the New York State polygon boundary
SELECT *
FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_H3`(
  JSON_OBJECT(
      'geography', (
        -- Dynamically retrieve the boundary geography for New York State
        SELECT state_geom
        FROM `bigquery-public-data.geo_us_boundaries.states`
        WHERE state = 'NY'
        LIMIT 1
      ),
      'types', ['grocery_store', 'convenience_store'],
      'business_status', ['OPERATIONAL'],
      'h3_resolution', 8,
      'wheelchair_accessible_entrance', TRUE
  )
)
ORDER BY count DESC;

Formato della risposta

La query restituisce una tabella riga per riga che mappa le celle direttamente ai conteggi spaziali:

Importante: l'oggetto JSON passato a PLACES_COUNT_PER_H3 è soggetto a un limite di dimensioni di 1 MB. Poiché l'area geografica di delimitazione viene passata direttamente all'interno del parametro JSON_OBJECT sotto la chiave 'geography', i confini spaziali complessi con migliaia di vertici possono superare questo limite. Per evitare errori di esecuzione, utilizza la funzione ST_SIMPLIFY per ridurre la complessità dei vertici prima di passare le geometrie alla funzione.

Esempio: conta i luoghi per cella H3 filtrati per brand

L'esempio seguente utilizza il filtro brand_ids per recuperare i conteggi dei luoghi e gli ID luogo di esempio per brand specifici, come Starbucks "1413758728321880760" e Dunkin "1314981297593671295":

DECLARE geo GEOGRAPHY;

-- Get the geography for New York City.
SET geo = (SELECT geometry FROM `bigquery-public-data.overture_maps.division_area`
  WHERE country = 'US' AND subtype = 'locality' AND names.primary = 'New York'  LIMIT 1);

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_H3`(
  JSON_OBJECT(
      'geography', geo,
      'h3_resolution', 8,
      'brand_ids', ["1413758728321880760", "1314981297593671295"],
      'business_status', ['OPERATIONAL']
    )
);

Visualizza i risultati H3 in modo dinamico in Looker Studio

Le seguenti immagini mostrano i dati di PLACES_COUNT_PER_H3 visualizzati in Looker Studio come mappa coropletica. Più scura è la cella H3, maggiore è la concentrazione di risultati:

Per importare i dati in Looker Studio:

1. Esegui la funzione riportata sopra in BigQuery per generare i risultati.
2. Nel riquadro dei risultati di BigQuery, fai clic su Apri in -> Looker Studio. I risultati vengono importati automaticamente in Looker Studio.

3. Looker Studio crea una pagina del report predefinita e la inizializza con un titolo, una tabella e un grafico a barre dei risultati.

   

4. Seleziona tutti i contenuti della pagina ed eliminali.

5. Fai clic su Inserisci -> Mappa coropletica per aggiungere una mappa coropletica al report.

6. In Tipi di grafici -> Configurazione, configura i campi come mostrato di seguito:

   

7. La mappa colorata viene visualizzata come sopra. Se vuoi, puoi selezionare Tipi di grafico -> Stile per configurare ulteriormente l'aspetto della mappa.

Per saperne di più sulla visualizzazione dei risultati di Places Insights, consulta Visualizza i risultati delle query.

Esempio: esegui query sui conteggi storici dei PDI per cella H3 con filtri specifici

Questo esempio mostra come eseguire query sui conteggi dei PDI storici in una griglia spaziale H3 per un mese di snapshot specifico utilizzando il filtro snapshot_date. Definisce un'area di ricerca geografica utilizzando un buffer intorno a una località e applica criteri aggiuntivi per il numero di connettori di ricarica EV utilizzando max_ev_charge_connector_count insieme a regular_opening_hours specifici.

SELECT *
FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_H3`(
  JSON_OBJECT(
    'geography', ST_BUFFER(ST_GEOGPOINT(-74.0060, 40.7128), 5000), -- 5km radius around NYC
    'h3_resolution', 8,
    'business_status', ['OPERATIONAL'],
    'snapshot_date', '2026-01', -- Target snapshot month (YYYY-MM)
    'max_ev_charge_connector_count', 3, -- Maximum connector count
    'regular_opening_hours', JSON_OBJECT(
      'monday', [JSON_OBJECT('start_time', '09:00', 'end_time', '12:00')]
    )
  )
);