In questo documento imparerai a utilizzare i dati di esempio degli ID luogo di Places Insights, utilizzando le funzioni di conteggio dei luoghi, insieme a ricerche mirate di Place Details per aumentare la fiducia nei risultati.
Per un'implementazione di riferimento dettagliata di questo pattern, consulta questo notebook esplicativo:
Esegui in Google Colab
Visualizza il codice sorgente su GitHub
Il pattern architettonico
Questo pattern architettonico ti offre un workflow ripetibile per colmare il divario tra l'analisi statistica di alto livello e la verifica del dato di fatto. Combinando la scalabilità di BigQuery con la precisione dell'API Places, puoi convalidare con sicurezza i risultati analitici. Questo è particolarmente utile per la selezione del sito, l'analisi della concorrenza e le ricerche di mercato in cui la fiducia nei dati è fondamentale.
Il nucleo di questo pattern prevede quattro passaggi chiave:
- Esegui analisi su larga scala: utilizza una funzione di conteggio dei luoghi di Places Insights in BigQuery per analizzare i dati sui luoghi in un'area geografica estesa, ad esempio un'intera città o regione.
- Isola ed estrai i campioni: identifica le aree di interesse (ad es. "hotspot" con alta densità) dai risultati aggregati ed estrai gli
sample_place_idsforniti dalla funzione. - Recupera i dettagli della verità di base: utilizza gli ID luogo estratti per effettuare chiamate mirate all'API Place Details per recuperare dettagli ricchi, reali per ogni luogo.
- Crea una visualizzazione combinata: sovrapponi i dati dettagliati sui luoghi alla mappa statistica iniziale di alto livello per verificare visivamente che i conteggi aggregati riflettano la realtà sul campo.
Flusso di lavoro della soluzione
Questo workflow ti consente di colmare il divario tra le tendenze a livello macro e i fatti a livello micro. Inizia con una visualizzazione statistica ampia e approfondisci strategicamente per verificare i dati con esempi specifici e reali.
Analizza la densità dei luoghi su larga scala con Places Insights
Il primo passo è comprendere il panorama a un livello elevato. Anziché recuperare migliaia di singoli punti di interesse (PDI), puoi eseguire una singola query per ottenere un riepilogo statistico.
La funzione PLACES_COUNT_PER_H3
di Places Insights
è ideale per questo scopo. Aggrega i conteggi dei PDI in un sistema di griglia esagonale
(H3), consentendoti di identificare rapidamente le aree di
alta o bassa densità in base a criteri specifici (ad es. ristoranti con una
valutazione elevata e operativi).
Di seguito è riportata una query di esempio. Tieni presente che dovrai fornire la geografia dell'area di ricerca. Per recuperare i dati sui confini geografici, puoi utilizzare un dataset aperto, ad esempio il set di dati pubblici BigQuery di Overture Maps Data BigQuery public dataset.
Per i confini dei dataset aperti utilizzati di frequente, ti consigliamo di materializzarli in una tabella nel tuo progetto. In questo modo, i costi di BigQuery vengono ridotti in modo significativo e le prestazioni delle query migliorano.
-- This query counts all highly-rated, operational restaurants
-- across a large geography, grouping them into H3 cells.
SELECT *
FROM
`places_insights___gb.PLACES_COUNT_PER_H3`(
JSON_OBJECT(
'geography', your_defined_geography,
'h3_resolution', 8,
'types', ['restaurant'],
'business_status', ['OPERATIONAL'],
'min_rating', 3.5
)
);
L'output di questa query fornisce una tabella di celle H3 e il conteggio dei luoghi all'interno di ciascuna, che costituisce la base per una mappa termica di densità.
Isola gli hotspot ed estrai gli ID luogo di esempio
Il risultato della funzione PLACES_COUNT_PER_H3 restituisce anche un array di sample_place_ids, fino a 250 ID luogo per elemento della risposta. Questi ID sono il collegamento dalla statistica aggregata ai singoli luoghi che contribuiscono a essa.
Il tuo sistema potrebbe prima identificare le celle più pertinenti dalla query iniziale.
Ad esempio, potresti selezionare le prime 20 celle con i conteggi più elevati. Poi, da questi hotspot, consolida gli sample_place_ids in un unico elenco.
Questo elenco rappresenta un campione curato dei PDI più interessanti delle aree più pertinenti, preparandoti per la verifica mirata.
Se elabori i risultati di BigQuery in Python utilizzando un DataFrame pandas, la logica per estrarre questi ID è semplice:
# Assume 'results_df' is a pandas DataFrame from your BigQuery query.
# 1. Identify the 20 busiest H3 cells by sorting and taking the top results.
top_hotspots_df = results_df.sort_values(by='count', ascending=False).head(20)
# 2. Extract and flatten the lists of sample_place_ids from these hotspots.
# The .explode() function creates a new row for each ID in the lists.
all_sample_ids = top_hotspots_df['sample_place_ids'].explode()
# 3. Create a final list of unique Place IDs to verify.
place_ids_to_verify = all_sample_ids.unique().tolist()
print(f"Consolidated {len(place_ids_to_verify)} unique Place IDs for spot-checking.")
Una logica simile può essere applicata se utilizzi altri linguaggi di programmazione.
Recupera i dettagli della verità di base con l'API Places
Con l'elenco consolidato di ID luogo, ora puoi passare dall'analisi su larga scala al recupero di dati specifici. Utilizzerai questi ID per eseguire query sull'API Place Details per informazioni dettagliate su ogni luogo di esempio.
Questo è un passaggio di convalida fondamentale. Mentre Places Insights ti ha indicato quanti ristoranti si trovavano in una zona, l'API Places ti indica quali ristoranti sono, fornendo il nome, l'indirizzo esatto, la latitudine/longitudine, la valutazione degli utenti e persino un link diretto alla loro posizione su Google Maps. In questo modo, i dati di esempio vengono arricchiti, trasformando gli ID astratti in luoghi concreti e verificabili.
Per l'elenco completo dei dati disponibili dall'API Place Details e il costo associato al recupero, consulta la documentazione dell'API.
Una richiesta all'API Places per un ID specifico utilizzando la libreria client Python avrà il seguente aspetto. Per maggiori dettagli, consulta gli esempi della libreria client dell'API Places (New).
# A request to fetch details for a single Place ID.
request = {"name": f"places/{place_id}"}
# Define the fields you want returned in the response as a comma-separated string.
fields_to_request = "formattedAddress,location,displayName,googleMapsUri"
# The response contains ground truth data.
response = places_client.get_place(
request=request,
metadata=[("x-goog-fieldmask", fields_to_request)]
)
Tieni presente che i campi di questa richiesta recuperano i dati da due SKU di fatturazione diversi.
formattedAddresselocationfanno parte dello SKU Place Details Essentials.displayNameegoogleMapsUrifanno parte dello SKU Place Details Pro.
Quando una singola richiesta Place Details include campi di più SKU, l'intera richiesta viene fatturata alla tariffa dello SKU di livello più alto. Pertanto, questa chiamata specifica verrà fatturata come richiesta Place Details Pro.
Per controllare i costi, utilizza sempre FieldMask per richiedere solo i campi richiesti dalla tua applicazione.
Crea una visualizzazione combinata per la convalida
Il passaggio finale consiste nel riunire entrambi i set di dati in un'unica visualizzazione. In questo modo, puoi controllare immediatamente e in modo intuitivo l'analisi iniziale. La visualizzazione deve avere due livelli:
- Livello di base: una mappa coropletica o termica generata dai risultati iniziali di
PLACES_COUNT_PER_H3, che mostra la densità complessiva dei luoghi nella tua area geografica. - Livello superiore: un insieme di singoli indicatori per ogni PDI di esempio, tracciati utilizzando le coordinate precise recuperate dall'API Places nel passaggio precedente.
La logica per la creazione di questa visualizzazione combinata è espressa in questo esempio di pseudocodice:
# Assume 'h3_density_data' is your aggregated data from Step 1.
# Assume 'detailed_places_data' is your list of place objects from Step 3.
# Create the base choropleth map from the H3 density data.
# The 'count' column determines the color of each hexagon.
combined_map = create_choropleth_map(
data=h3_density_data,
color_by_column='count'
)
# Iterate through the detailed place data to add individual markers.
for place in detailed_places_data:
# Construct the popup information with key details and a link.
popup_html = f"""
<b>{place.name}</b><br>
Address: {place.address}<br>
<a href="{place.google_maps_uri}" target="_blank">View on Maps</a>
"""
# Add a marker for the current place to the base map.
combined_map.add_marker(
location=[place.latitude, place.longitude],
popup=popup_html,
tooltip=place.name
)
# Display the final map with both layers.
display(combined_map)
Sovrapponendo gli indicatori specifici della verità di base alla mappa di densità di alto livello, puoi verificare immediatamente che le aree identificate come hotspot contengano effettivamente un'alta concentrazione dei luoghi che stai analizzando. Questa conferma visiva aumenta in modo significativo la fiducia nelle conclusioni basate sui dati.
Conclusione
Questo pattern architettonico fornisce un metodo efficace e solido per convalidare gli approfondimenti geospaziali su larga scala. Sfruttando Places Insights per un'analisi ampia e scalabile e l'API Place Details per una verifica mirata della verità di base, crei un potente ciclo di feedback. In questo modo, le tue decisioni strategiche, sia nella selezione di siti di vendita al dettaglio sia nella pianificazione della logistica, si basano su dati non solo statisticamente significativi, ma anche verificabilmente accurati.
Passaggi successivi
- Esplora altre funzioni di conteggio dei luoghi per scoprire come possono rispondere a diverse domande analitiche.
- Consulta la documentazione dell'API Places per scoprire altri campi che puoi richiedere per arricchire ulteriormente l'analisi.
Collaboratori
Henrik Valve | Ingegnere DevX