Inizia a utilizzare Dati di Places

Le funzioni di conteggio dei luoghi sono query SQL predefinite che vengono eseguite in BigQuery e sono il modo consigliato per eseguire query sul set di dati Places Insights per recuperare conteggi esatti e ID luogo. Anche se puoi anche eseguire query sul set di dati direttamente, i due metodi di query gestiscono le soglie di privacy e le aree di ricerca:

• Le funzioni di conteggio dei luoghi possono restituire qualsiasi conteggio, incluso 0, ma applicano un' area di ricerca minima di 40,0 metri per 40,0 metri (1600 m²) (40,0 metri per 40,0 metri / 1600 m²). Le funzioni restituiscono anche gli ID luogo, che possono essere utilizzati per cercare informazioni sui singoli luoghi e supportare l'analisi storica dei PDI negli snapshot mensili precedenti utilizzando filtri di data facoltativi.

• Le query sui set di dati dei luoghi possono restituire solo conteggi pari o superiori a 5 (omettendo i conteggi bassi da 0 a 4 per preservare la privacy differenziale), ma non applicano limitazioni alle dimensioni dell'area di ricerca.

A meno che tu non debba eseguire analisi spaziali complesse, ti consigliamo di iniziare con le funzioni di conteggio dei luoghi come PLACES_COUNT_PER_H3. Fornisce insight immediati sulla densità spaziale nelle celle della griglia standardizzate, restituisce gli ID luogo per l'ispezione della verità di base ed è progettata appositamente per l'ingegneria delle funzionalità geospaziali e i modelli di ML.

Questo prodotto o funzionalità è in anteprima (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere un supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le offerte pre-GA sono coperte da Google Termini specifici di servizio di Google Maps Platform. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Selezionare la funzione di conteggio dei luoghi ottimale

Places Insights supporta diverse funzioni spaziali. Per un'esecuzione ottimizzata delle query, l'elaborazione parallela e la scalabilità batch, ti consigliamo di utilizzare le seguenti funzioni:

• PLACES_COUNT_PER_H3: restituisce una tabella BigQuery dei conteggi dei luoghi per cella H3. Questa funzione è consigliata per l'analisi della densità regionale e la creazione di mappe termiche coropletiche.
• PLACES_COUNT_V2: restituisce una tabella contenente i conteggi dei luoghi e gli ID luogo di esempio. Questa funzione accetta un parametro della tabella contenente le geografie di input. Passando direttamente un'intera tabella, il motore di esecuzione di BigQuery può distribuire il carico di lavoro ed elaborare le intersezioni spaziali in parallelo, consentendo un'elaborazione batch altamente efficiente per l'analisi su larga scala.
• PLACES_COUNT_PER_TYPE_V2: Restituisce una tabella di conteggi dei luoghi e ID luogo di esempio, classificati per tipo di luogo. Analogamente a PLACES_COUNT_V2, il passaggio delle geografie di input come parametro della tabella consente a BigQuery di parallelizzare in modo nativo le intersezioni spaziali su set di dati di grandi dimensioni.
• PLACES_COUNT_CHANGE: restituisce una tabella di conteggi dei luoghi più gli ID luogo aggiunti e rimossi tra due mesi specificati. Analogamente a PLACES_COUNT_V2, il passaggio delle geografie di input come parametro della tabella consente a BigQuery di parallelizzare in modo nativo le intersezioni spaziali su set di dati di grandi dimensioni.

Oltre ai conteggi dei luoghi, queste funzioni restituiscono anche fino a 250 ID luogo per elemento della risposta.

Gli ID luogo possono essere utilizzati con:

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

Nota: puoi accedere alle funzioni di conteggio dei luoghi per le stesse città e gli stessi paesi a cui hai accesso.

Eseguire query con le funzioni di conteggio dei luoghi

Utilizza il seguente formato per chiamare le funzioni: [project name (optional)].[table name].[function name].

Se hai modificato il nome del set di dati collegato durante la configurazione di Places Insights, utilizza il nome personalizzato anziché i nomi delle tabelle predefiniti. Puoi anche includere facoltativamente il nome del progetto. Se non ne viene incluso uno, la query utilizza per impostazione predefinita il progetto attivo.

Ad esempio:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

Utilizza un JSON_OBJECT per passare gli argomenti alla funzione.

Nota: quando utilizzi una funzione di conteggio dei luoghi, specifica la funzione nella clausola FROM e ometti WITH_AGGREGATION_THRESHOLD.

Filtrare i risultati delle query utilizzando parametri sensibili alle maiuscole/minuscole

Le funzioni di conteggio dei luoghi supportano molti filtri per perfezionare la ricerca. Questi parametri (ad esempio price_level o types) sono sensibili alle maiuscole/minuscole e devono corrispondere esattamente ai nomi dei parametri. Per un elenco completo delle opzioni, consulta il riferimento ai parametri dei filtri.

Eseguire query sugli snapshot storici con snapshot_date

Per impostazione predefinita, le funzioni di conteggio dei luoghi eseguono query sullo snapshot dei dati più recente disponibile. Per analizzare i dati dei luoghi così come esistevano durante un mese passato specifico, aggiungi il parametro facoltativo snapshot_date al tuo JSON_OBJECT.

• Formato: YYYY-MM (ad esempio, '2026-07').
• Valore predefinito: se omesso, la funzione esegue automaticamente query sull'ultimo snapshot.

L'esempio seguente esegue query sui conteggi dei ristoranti nelle aree di ricerca registrate nello snapshot di luglio 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
  )
);

Nell'esempio successivo, applichi i filtri per limitare la ricerca in base alla valutazione minima degli utenti, al livello di prezzo, allo stato dell'attività e se il ristorante ammette i cani, utilizzando la funzione PLACES_COUNT_V2.

Innanzitutto, utilizza la tabella delle geografie di input o preparane una con le geografie scelte:

Importante: devi creare il set di dati contenente la tabella delle geografie di input nella stessa regione del set di dati Places Insights collegato. Se le località non corrispondono, BigQuery restituisce un errore.

-- 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
);

Poi, chiama PLACES_COUNT_V2 con la tabella e l'oggetto JSON contenente i filtri. Il raggio di ricerca è incluso nei filtri JSON e verrà applicato a ogni punto della tabella 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
      )
);

Nota: includi il filtro business_status per assicurarti di ottenere il conteggio di attività OPERATIONAL. In caso contrario, il conteggio include le attività chiuse.

Esempio: eseguire query sui conteggi dei ristoranti e sulle località dei brand con PLACES_COUNT_V2

L'esempio seguente utilizza la funzione PLACES_COUNT_V2 con la tabella delle geografie di input personalizzata my_search_areas per restituire il numero di ristoranti operativi entro 1000 metri dall'Empire State Building e da Times Square a New York nel luglio 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'
      )
);

La risposta è una tabella BigQuery che contiene geo_id, la geografia, il conteggio e un campione di ID luogo.

L'esempio seguente utilizza la funzione PLACES_COUNT_V2 per filtrare in base a ID brand specifici. In questo esempio, filtriamo le località Starbucks utilizzando l'ID brand "1413758728321880760".

Per trovare gli ID brand dei brand in base ai quali vuoi filtrare, esegui una query sulla brands tabella per il tuo set di dati (ad esempio, places_insights___us.brands). Per ulteriori informazioni sul set di dati dei brand, consulta Scrivere una query utilizzando i dati dei brand.

Ad esempio, per trovare l'ID brand di "Starbucks":

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

Dopo aver ottenuto gli ID brand, puoi utilizzarli nel filtro brand_ids come mostrato nella query seguente:

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"]
      )
);

Nota: i parametri obbligatori e facoltativi variano per ogni funzione di conteggio dei luoghi come descritto in filtri.

Visualizzare l'output delle query con gli strumenti di Google Cloud

Gli strumenti di analisi e business intelligence tools ti aiutano a scoprire insight dai dati di BigQuery. BigQuery supporta diversi strumenti di visualizzazione dei dati di Google e di terze parti che puoi utilizzare per analizzare i risultati delle funzioni sui dati di Places Insights.

Per un esempio di visualizzazione dei risultati di una funzione, consulta Visualizzare i risultati all'interno del riferimento PLACES_COUNT_PER_H3. Per ulteriori informazioni sulla visualizzazione dei risultati di Places Insights, consulta Visualizzare i risultati delle query.

Limitazioni e requisiti delle funzioni

Le funzioni di conteggio dei luoghi presentano le seguenti limitazioni e requisiti:

• Le funzioni supportano solo gli insight COUNT.
• È richiesta un'area di ricerca minima di 40,0 metri per 40,0 metri (1600 m²) (40,0 metri per 40,0 metri/ 1600 m²).
• Limite di dimensioni dell'input dei parametri: l'oggetto JSON passato come parametro alle funzioni è limitato a 1 MB. L'impatto di questo limite dipende dalla versione della funzione:
  • Per le funzioni V2 (PLACES_COUNT_V2, PLACES_COUNT_PER_TYPE_V2, PLACES_COUNT_CHANGE), questo limite si applica solo all'oggetto JSON dei filtri. Poiché le geografie vengono fornite separatamente utilizzando un parametro della tabella, queste funzioni possono essere scalate a un numero molto maggiore di geografie di input senza raggiungere il limite di dimensioni JSON.
  • Per PLACES_COUNT_PER_H3, PLACES_COUNT, PLACES_COUNT_PER_TYPE, e PLACES_COUNT_PER_GEO, questo limite si applica all'intero oggetto JSON, incluse tutte le definizioni delle geografie. Ciò potrebbe limitare il numero di geografie che possono essere elaborate in una singola chiamata.
• Nessun supporto per il filtraggio in base all'ID luogo o al componente dell'indirizzo.
• Puoi accedere alle funzioni di conteggio dei luoghi solo per le città e i paesi a cui hai eseguito l'iscrizione. Consulta Configurare Places Insights per l'accesso al set di dati.
• I parametri dei filtri (ad esempio geography o types) sono sensibili alle maiuscole/minuscole e devono corrispondere esattamente ai nomi dei parametri, altrimenti la query non andrà a buon fine.