Consultar contagens de PDI por H3

A função PLACES_COUNT_PER_H3 agrega dados de lugares 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 FROM do SQL, 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á definida como o projeto ativo.
• LINKED_DATASET_NAME: o nome do seu conjunto de dados do Insights de Lugares inscrito (por exemplo, places_insights___us).
• filters (JSON): um objeto JSON construído 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, linha ou polígono) a ser indexada.
• h3_resolution (INTEGER): o nível de resolução da célula H3 (os valores aceitos 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. Consulte 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:

Agregar a densidade regional de PDIs usando PLACES_COUNT_PER_H3

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

Exemplo: contar supermercados e lojas de conveniência acessíveis para cadeirantes no estado de Nova York

Esta consulta agrega lojas de conveniência e supermercados operacionais e acessíveis para cadeirantes 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 contagens espaciais:

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 resultados H3 dinamicamente 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. Opcionalmente, 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 da consulta.

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. Ele 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ículos elétricos 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')]
    )
  )
);