Inizia a utilizzare Dati di Places

Le funzioni Places Count 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. Sebbene sia possibile anche eseguire query direttamente sul set di dati, i due metodi di query gestiscono le soglie di privacy e le aree di ricerca:

• Le funzioni Places Count 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 su singoli luoghi, e supportano l'analisi dei PDI storici in base agli snapshot mensili passati utilizzando filtri di data facoltativi.

• Le query sul set di dati 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 impongono 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 in celle di griglia standardizzate, restituisce ID luogo per l'ispezione dei dati di fatto ed è progettata appositamente per il feature engineering geospaziale e i modelli ML.

Seleziona la funzione Places Count ottimale

Places Insights supporta diverse funzioni spaziali. Per l'esecuzione ottimizzata delle query, l'elaborazione parallela e la scalabilità dei 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 mappatura termica coropletica.
• PLACES_COUNT_V2: restituisce una tabella contenente i conteggi dei luoghi e gli ID luogo di esempio. Questa funzione accetta un parametro di tabella contenente le aree geografiche di input. Passando direttamente un'intera tabella, il motore di esecuzione di BigQuery può distribuire il workload ed elaborare le intersezioni spaziali in parallelo, consentendo un'elaborazione batch altamente efficiente per analisi su larga scala.
• PLACES_COUNT_PER_TYPE_V2: restituisce una tabella dei conteggi dei luoghi e degli ID luogo di esempio, classificati per tipo di luogo. Analogamente a PLACES_COUNT_V2, il passaggio delle aree geografiche di input come parametro della tabella consente a BigQuery di parallelizzare in modo nativo le intersezioni spaziali tra set di dati di grandi dimensioni.
• PLACES_COUNT_CHANGE: restituisce una tabella dei conteggi dei luoghi, oltre agli ID luogo aggiunti e rimossi tra due mesi specifici. Analogamente a PLACES_COUNT_V2, il passaggio delle aree geografiche 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.

Esegui query con le funzioni Places Count

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. Se vuoi, puoi anche includere il nome del progetto. Se non ne viene incluso uno, la query viene eseguita per impostazione predefinita sul progetto attivo.

Ad esempio:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

Utilizza un JSON_OBJECT per passare argomenti alla funzione.

Nota: Quando si utilizza una funzione di conteggio dei luoghi, specificare la funzione nella clausola FROM e omettere WITH_AGGREGATION_THRESHOLD.

Filtra i risultati delle query utilizzando parametri sensibili alle maiuscole

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

Esegui query sugli snapshot storici con snapshot_date

Per impostazione predefinita, le funzioni Places Count eseguono query sullo snapshot dei dati più recente disponibile. Per analizzare i dati dei luoghi così come esistevano durante un mese specifico del passato, aggiungi il parametro facoltativo snapshot_date alla tua JSON_OBJECT.

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

La seguente query di esempio restituisce il numero di ristoranti nelle aree di ricerca, come registrato 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 alla possibilità di portare cani nel ristorante, utilizzando la funzione PLACES_COUNT_V2.

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

Importante: devi creare il set di dati contenente la tabella delle aree geografiche 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
);

Successivamente, 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 intorno 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 delle attività OPERATIONAL. In caso contrario, il conteggio include le attività chiuse.

Esempio: esegui query sul numero di ristoranti e sulle sedi dei brand con PLACES_COUNT_V2

L'esempio seguente utilizza la funzione PLACES_COUNT_V2 con la tabella di geografia 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 City a 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, l'area geografica, 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 sedi di Starbucks utilizzando l'ID brand "1413758728321880760".

Per trovare gli ID dei brand in base ai quali vuoi filtrare, esegui una query sulla tabella brands per il tuo set di dati (ad esempio places_insights___us.brands). Per ulteriori informazioni sul set di dati dei brand, consulta Scrivi 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 seguente query:

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 Places Count, come descritto in Filtri.

Visualizza l'output delle query con gli strumenti Google Cloud

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

Per un esempio di visualizzazione dei risultati di una funzione, consulta Visualizza i risultati nel riferimento PLACES_COUNT_PER_H3. Per saperne di più sulla visualizzazione dei risultati di Places Insights, consulta Visualizza i risultati delle query.

Limitazioni e requisiti delle funzioni

Le funzioni Places Count presentano le seguenti limitazioni e requisiti:

• Le funzioni supportano solo gli insight COUNT.
• È richiesta un'area di ricerca minima di 40,0 x 40,0 metri (1600 m²) (40,0 x 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 aree geografiche vengono fornite separatamente utilizzando un parametro della tabella, queste funzioni possono scalare a un numero molto maggiore di aree geografiche 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 geografiche. Ciò potrebbe limitare il numero di aree geografiche che possono essere elaborate in una singola chiamata.
• Nessun supporto per il filtro in base all'ID luogo o al componente dell'indirizzo.
• Puoi accedere alle funzioni Places Count solo per le città e i paesi per cui hai sottoscritto un abbonamento. Consulta Configura Places Insights per l'accesso al set di dati.
• I parametri di filtro (ad esempio geography o types) sono sensibili alle maiuscole e devono corrispondere esattamente ai nomi dei parametri, altrimenti la query non andrà a buon fine.