Consultar contagens de PDI por H3

A função PLACES_COUNT_PER_H3 agrega dados de pontos de interesse (PDIs) em células de grade espacial H3 padronizadas em uma resolução especificada. Essa função é o caminho recomendado para análise de densidade regional, mapeamento competitivo e geração de mapas de calor coropléticos hexagonais.

Para chamar a função PLACES_COUNT_PER_H3, use uma cláusula SQL FROM, porque a função retorna uma tabela.

Sintaxe e parâmetros

SELECT * FROM `PROJECT_NAME.LINKED_DATASET_NAME.PLACES_COUNT_PER_H3`(
  filters
)

Parâmetros

• PROJECT_NAME: o nome do seu projeto do Google Cloud. Se você não especificar um nome de projeto, a consulta será padronizada para o projeto ativo.
• LINKED_DATASET_NAME: o nome do conjunto de dados de Insights de Lugares que você assinou (por exemplo, places_insights___us).
• filters (JSON): um objeto JSON criado usando JSON_OBJECT que contém parâmetros de filtro de chave-valor.

Filtros JSON obrigatórios

• geography (GEOGRAPHY): a área de pesquisa delimitadora (ponto, string de linha ou polígono) a ser indexada.
• h3_resolution (INTEGER): o nível de resolução da célula H3 (os valores compatíveis variam de 0 a 11).

Filtros JSON opcionais

• Parâmetros adicionais, como types, business_status, price_level e min_rating, para filtrar os lugares contados em cada célula. Veja a lista completa de parâmetros de filtro.

Esquema da tabela de saída

A função retorna uma tabela do BigQuery com uma linha por índice de célula H3 que cruza a geometria de destino:

Nome da coluna	Tipo de dado	Descrição
h3_cell_index	STRING	O identificador exclusivo do índice H3 da célula.
geography	GEOGRAPHY	Um polígono que representa o limite físico da célula H3.
count	INTEGER	A contagem exata total de lugares operacionais correspondentes nessa célula H3 específica ou zero se não houver correspondências.
sample_place_ids	ARRAY<STRING>	Uma matriz de até 250 IDs de lugar localizados nessa célula, permitindo consultas diretas de informações empíricas usando a API Places.

Agregue a densidade regional de PDIs usando PLACES_COUNT_PER_H3

A função processa a área geográfica especificada nos filtros, identifica todos os hexágonos H3 que se cruzam na resolução de destino e retorna as contagens exatas de lugares e os IDs de lugar de cada hexágono.

Exemplo: contar as mercearias e lojas de conveniência com acessibilidade para pessoas em cadeira de rodas no estado de Nova York

Essa consulta agrega lojas de conveniência e de alimentos em funcionamento e com acessibilidade para pessoas em cadeira de rodas no estado de Nova York usando um nível de resolução H3 de 8. A geometria de limite do estado de Nova York é consultada dinamicamente no conjunto de dados público bigquery-public-data.geo_us_boundaries.states.

-- Query POI count per H3 cell intersecting the New York State polygon boundary
SELECT *
FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_H3`(
  JSON_OBJECT(
      'geography', (
        -- Dynamically retrieve the boundary geography for New York State
        SELECT state_geom
        FROM `bigquery-public-data.geo_us_boundaries.states`
        WHERE state = 'NY'
        LIMIT 1
      ),
      'types', ['grocery_store', 'convenience_store'],
      'business_status', ['OPERATIONAL'],
      'h3_resolution', 8,
      'wheelchair_accessible_entrance', TRUE
  )
)
ORDER BY count DESC;

Formato da resposta

A consulta gera uma tabela linha por linha que mapeia as células diretamente para as contagens espaciais:

Importante: o objeto JSON transmitido para PLACES_COUNT_PER_H3 está sujeito a um limite de tamanho estrito de 1 MB. Como a região geográfica delimitadora é transmitida diretamente no parâmetro JSON_OBJECT na chave 'geography', limites espaciais complexos com milhares de vértices podem exceder esse limite. Para evitar falhas de execução, use a função ST_SIMPLIFY para reduzir a complexidade do vértice antes de transmitir geometrias para a função.

Exemplo: contar lugares por célula H3 filtrada por marca

O exemplo a seguir usa o filtro brand_ids para recuperar contagens de lugares e IDs de lugares de amostra para marcas específicas, como Starbucks "1413758728321880760" e Dunkin "1314981297593671295":

DECLARE geo GEOGRAPHY;

-- Get the geography for New York City.
SET geo = (SELECT geometry FROM `bigquery-public-data.overture_maps.division_area`
  WHERE country = 'US' AND subtype = 'locality' AND names.primary = 'New York'  LIMIT 1);

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_H3`(
  JSON_OBJECT(
      'geography', geo,
      'h3_resolution', 8,
      'brand_ids', ["1413758728321880760", "1314981297593671295"],
      'business_status', ['OPERATIONAL']
    )
);

Visualizar os resultados do H3 de forma dinâmica no Looker Studio

As imagens a seguir mostram dados de PLACES_COUNT_PER_H3 exibidos no Looker Studio como um mapa preenchido. Quanto mais escura a célula H3, maior a concentração de resultados:

Para importar seus dados para o Looker Studio:

1. Execute a função acima no BigQuery para gerar os resultados.
2. No painel de resultados do BigQuery, clique em Abrir em -> Looker Studio. Os resultados são importados automaticamente para o Looker Studio.

3. O Looker Studio cria uma página de relatório padrão e a inicializa com um título, uma tabela e um gráfico de barras dos resultados.

   

4. Selecione tudo na página e exclua.

5. Clique em Inserir -> Mapa preenchido para adicionar um mapa preenchido ao relatório.

6. Em Tipos de gráfico -> Configuração, configure os campos conforme mostrado abaixo:

   

7. O mapa preenchido aparece como acima. Se quiser, selecione Tipos de gráfico -> Estilo para configurar ainda mais a aparência do mapa.

Para mais informações sobre como visualizar os resultados do Insights de Lugares, consulte Visualizar resultados de consultas.

Exemplo: consultar contagens históricas de PDIs por célula H3 com filtros específicos

Este exemplo demonstra como consultar contagens históricas de PDIs em uma grade espacial H3 para um mês de snapshot específico usando o filtro snapshot_date. Ela define uma área de pesquisa geográfica usando um buffer ao redor de um local e aplica critérios adicionais para contagens de conectores de carregamento de VE usando max_ev_charge_connector_count com regular_opening_hours específicos.

SELECT *
FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_H3`(
  JSON_OBJECT(
    'geography', ST_BUFFER(ST_GEOGPOINT(-74.0060, 40.7128), 5000), -- 5km radius around NYC
    'h3_resolution', 8,
    'business_status', ['OPERATIONAL'],
    'snapshot_date', '2026-01', -- Target snapshot month (YYYY-MM)
    'max_ev_charge_connector_count', 3, -- Maximum connector count
    'regular_opening_hours', JSON_OBJECT(
      'monday', [JSON_OBJECT('start_time', '09:00', 'end_time', '12:00')]
    )
  )
);