Validar dados do Place Insights usando IDs de lugar de amostra

Neste documento, você vai aprender a usar dados de IDs de lugar de amostra do Places Insights usando funções de contagem de lugares, além de pesquisas direcionadas de detalhes do lugar para aumentar a confiança nos seus resultados.

Um mapa de calor de densidade de lugares em Londres, com marcadores individuais sobrepostos para validar os dados estatísticos.

O padrão arquitetônico

Esse padrão arquitetônico oferece um fluxo de trabalho repetível para reduzir a diferença entre a análise estatística de alto nível e a verificação de informações empíricas. Ao combinar a escala do BigQuery com a precisão da API Places, você pode validar seus resultados analíticos com confiança. Isso é especialmente útil para seleção de sites, análise da concorrência e pesquisa de mercado, em que a confiança nos dados é fundamental.

O núcleo desse padrão envolve quatro etapas principais:

  1. Faça análises em grande escala:use uma função de contagem de lugares dos Insights de lugares no BigQuery para analisar dados de lugares em uma grande área geográfica, como uma cidade ou região inteira.
  2. Isolar e extrair amostras:identifique áreas de interesse (por exemplo, "pontos de acesso" com alta densidade) dos resultados agregados e extrair o sample_place_ids fornecido pela função.
  3. Recuperar detalhes de informações empíricas:use os IDs de lugar extraídos para fazer chamadas direcionadas à API Place Details e buscar detalhes avançados e reais de cada lugar.
  4. Crie uma visualização combinada:coloque os dados detalhados do lugar sobre o mapa estatístico inicial de alto nível para validar visualmente que as contagens agregadas refletem a realidade no local.

Fluxo de trabalho da solução

Esse fluxo de trabalho permite diminuir a distância entre tendências macro e fatos micro. Você começa com uma visão ampla e estatística e faz um detalhamento estratégico para verificar os dados com exemplos específicos e reais.

Analisar a densidade de lugares em escala com o Places Insights

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 Places Insights é ideal para isso. Ele agrega contagens de PDI 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: Você precisará informar a geografia da sua área de pesquisa. Um conjunto de dados aberto, como o Overture Maps Data BigQuery público, 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 das consultas.

-- 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 fornece 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.

Uma tabela de resultados de consultas do BigQuery mostrando colunas para h3_cell_index, count e sample_place_ids.

Isolar áreas de risco 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 lugar por elemento da resposta. Esses IDs são o link da estatística agregada para os lugares individuais que contribuem para ela.

Primeiro, o sistema pode identificar as células mais relevantes da consulta inicial. Por exemplo, você pode selecionar as 20 células principais com as contagens mais altas. Em seguida, consolide os sample_place_ids desses pontos de acesso 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 em Python usando um DataFrame pandas, a lógica para extrair esses IDs é simples:

# 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 se você usar outras linguagens de programação.

Recuperar detalhes de verdade absoluta com a API Places

Com sua lista consolidada de IDs de lugar, agora você faz a transição de análises em grande escala para 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 exemplo.

Essa é uma etapa de validação essencial. Enquanto o Places Insights informava quantos restaurantes havia em uma área, a API Places informa quais são eles, fornecendo o nome, o endereço exato, a latitude/longitude, a avaliação do usuário e até mesmo um link direto para a localização 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. O FieldMask é definido na solicitação para controlar os dados retornados da API.

Uma solicitação para a API Places de um ID específico usando a biblioteca de cliente Python seria assim:

# 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 = "displayName,formattedAddress,location,googleMapsUri"

# The response contains ground truth data.
response = places_client.get_place(
    request=request,
    metadata=[("x-goog-fieldmask", fields_to_request)]
)

Confira mais detalhes nos exemplos da biblioteca de cliente da API Places (nova).

Criar uma visualização combinada para validação

A última etapa é 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:

  1. Camada de base:um mapa coroplético ou de calor gerado com base nos resultados iniciais de PLACES_COUNT_PER_H3, mostrando a densidade geral de lugares na sua região geográfica.
  2. Camada superior:um conjunto de marcadores individuais para cada PDI 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 de verdade no mapa de densidade de alto nível, você pode confirmar instantaneamente que as áreas identificadas como pontos de interesse contêm, de fato, uma alta concentração dos lugares que você está analisando. Essa confirmação visual aumenta muito a confiança 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 usar o Places Insights para análises amplas e escalonáveis e a API Place Details para verificações direcionadas e de informações empíricas, você cria um ciclo de feedback eficiente. 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 estatisticamente significativos e verificavelmente precisos.

Próximas etapas

Colaboradores

Henrik Valve | Engenheiro de DevX