Neste documento, você vai aprender a usar dados de exemplo de IDs de lugares do Places Insights, usando funções de contagem de lugares, além de pesquisas direcionadas do Place Details para gerar confiança nos seus resultados.
Para uma implementação de referência detalhada desse padrão, consulte este notebook explicativo:
Executar no Google Colab
Ver origem no GitHub
O padrão arquitetônico
Esse padrão arquitetônico oferece um fluxo de trabalho repetível para preencher a lacuna entre a análise estatística de alto nível e a verificação da verdade. Ao combinar a escala do BigQuery com a precisão da API Places, você pode validar com confiança suas descobertas analíticas. Isso é especialmente útil para seleção de sites, análise de concorrentes e pesquisa de mercado, em que a confiança nos dados é fundamental.
O núcleo desse padrão envolve quatro etapas principais:
- Realizar análises em grande escala: use uma função de contagem de lugares do Insights de Lugares no BigQuery para analisar dados de lugares em uma grande área geográfica, como uma cidade ou região inteira.
- Isolar e extrair amostras:identifique áreas de interesse (por exemplo, "pontos de acesso" com alta densidade) nos resultados agregados e extraia os
sample_place_idsfornecidos pela função. - Recuperar detalhes da verdade: use os IDs de lugares extraídos para fazer chamadas direcionadas à API Place Details para buscar detalhes ricos, reais de cada lugar.
- Criar uma visualização combinada:coloque os dados detalhados do lugar sobre o mapa estatístico de alto nível inicial para validar visualmente se as contagens agregadas refletem a realidade.
Fluxo de trabalho da solução
Esse fluxo de trabalho permite preencher a lacuna entre tendências macro e fatos micro. Você começa com uma visão estatística ampla e detalha estrategicamente para verificar os dados com exemplos específicos do mundo real.
Analisar a densidade de lugares em escala com o Insights de Lugares
A primeira etapa é entender o cenário em um nível alto. Em vez de buscar milhares de pontos de interesse (POIs) individuais, você pode executar uma única consulta para receber um resumo estatístico.
A função PLACES_COUNT_PER_H3
do Insights de Lugares é ideal para isso. Ela agrega contagens de POIs em um sistema de grade hexagonal
(H3), permitindo identificar rapidamente áreas de
alta ou baixa densidade com base nos seus critérios específicos (por exemplo, restaurantes com uma
classificação alta que estão em funcionamento).
Confira um exemplo de consulta: Observe que você precisará fornecer a geografia da área de pesquisa. Um conjunto de dados aberto, como o Overture Maps Data BigQuery public dataset pode ser usado para recuperar dados de limites geográficos.
Para limites de conjuntos de dados abertos usados com frequência, recomendamos materializá-los em uma tabela no seu próprio projeto. Isso reduz significativamente os custos do BigQuery e melhora o desempenho da consulta.
-- 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
)
);
A saída dessa consulta oferece uma tabela de células H3 e a contagem de lugares em cada uma delas, formando a base para um mapa de calor de densidade.
Isolar pontos de acesso e extrair IDs de lugares de amostra
O resultado da função PLACES_COUNT_PER_H3 também retorna uma matriz de sample_place_ids, até 250 IDs de lugares por elemento da resposta. Esses IDs são o link da estatística agregada para os lugares individuais que contribuem para ela.
Seu sistema pode primeiro identificar as células mais relevantes da consulta inicial.
Por exemplo, você pode selecionar as 20 principais células com as contagens mais altas. Em seguida, desses pontos de acesso, consolide os sample_place_ids em uma única lista.
Essa lista representa uma amostra selecionada dos POIs mais interessantes das áreas mais relevantes, preparando você para a verificação direcionada.
Se você estiver processando os resultados do BigQuery no Python usando um DataFrame do pandas, a lógica para extrair esses IDs será direta:
# 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.")
Uma lógica semelhante pode ser aplicada ao usar outras linguagens de programação.
Recuperar detalhes da verdade com a API Places
Com sua lista consolidada de IDs de lugares, você agora faz a transição de análises em grande escala para a recuperação de dados específicos. Você vai usar esses IDs para consultar a API Place Details e receber informações detalhadas sobre cada local de amostra.
Essa é uma etapa de validação essencial. Enquanto o Insights de Lugares informa quantos restaurantes estão em uma área, a API Places informa quais restaurantes são, fornecendo o nome, o endereço exato, a latitude/longitude, a avaliação de usuários e até mesmo um link direto para o local no Google Maps. Isso enriquece seus dados de amostra, transformando IDs abstratos em lugares concretos e verificáveis.
Para conferir a lista completa de dados disponíveis na API Place Details e o custo associado à recuperação, consulte a documentação da API .
Uma solicitação à API Places para um ID específico usando a biblioteca de cliente Python seria assim. Consulte os exemplos da biblioteca de cliente da API Places (nova) para mais detalhes.
# 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)]
)
Os campos nessa solicitação extraem dados de duas SKUs de faturamento diferentes.
formattedAddresselocationfazem parte da SKU Place Details Essentials.displayNameegoogleMapsUrifazem parte da SKU Place Details Pro.
Quando uma única solicitação do Place Details inclui campos de várias SKUs, toda a solicitação é faturada na taxa da SKU de nível mais alto. Portanto, essa chamada específica será faturada como uma solicitação do Place Details Pro.
Para controlar seus custos, sempre use o FieldMask para solicitar apenas os campos necessários para seu aplicativo.
Criar uma visualização combinada para validação
A etapa final é reunir os dois conjuntos de dados em uma única visualização. Isso oferece uma maneira imediata e intuitiva de verificar sua análise inicial. Sua visualização precisa ter duas camadas:
- Camada de base:um mapa coroplético ou de calor gerado pelos resultados iniciais de
PLACES_COUNT_PER_H3, mostrando a densidade geral de lugares na sua área geográfica. - Camada superior:um conjunto de marcadores individuais para cada POI de amostra, plotados usando as coordenadas precisas recuperadas da API Places na etapa anterior.
A lógica para criar essa visualização combinada é expressa neste exemplo de pseudocódigo:
# 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)
Ao sobrepor os marcadores específicos e verdadeiros no mapa de densidade de alto nível, você pode confirmar instantaneamente que as áreas identificadas como pontos de acesso contêm, de fato, uma alta concentração dos lugares que você está analisando. Essa confirmação visual gera confiança significativa nas suas conclusões baseadas em dados.
Conclusão
Esse padrão arquitetônico oferece um método robusto e eficiente para validar insights geoespaciais em grande escala. Ao aproveitar o Insights de Lugares para análises amplas e escalonáveis e a API Place Details para verificações direcionadas e informações empíricas, você cria um ciclo de feedback poderoso. Isso garante que suas decisões estratégicas, seja na seleção de sites de varejo ou no planejamento logístico, sejam baseadas em dados que não são apenas estatisticamente significativos, mas também verificavelmente precisos.
Próximas etapas
- Explore outras funções de contagem de lugares para saber como elas podem responder a diferentes perguntas analíticas.
- Consulte a documentação da API Places para descobrir outros campos que você pode solicitar para enriquecer ainda mais sua análise.
Colaboradores
Henrik Valve | Engenheiro de DevX