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 hexagonais de coropletas.

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 a que você se inscreveu (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:

Nome da coluna	Tipo de dado	Descrição
h3_cell_index	STRING	O identificador de índice H3 exclusivo 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 nenhum lugar corresponder.
sample_place_ids	ARRAY<STRING>	Uma matriz de até 250 IDs de lugares localizados nessa célula, permitindo consultas diretas de verdade básica usando a API Places.

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

Essa 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:

Importante: o objeto JSON transmitido para PLACES_COUNT_PER_H3 está sujeito a um limite de tamanho estrito de 1 MB. Como a geografia delimitadora é transmitida diretamente dentro do JSON_OBJECT parâmetro na chave 'geography', limites espaciais complexos com milhares de vértices podem exceder esse limite. Para evitar falhas de execução, use a ST_SIMPLIFY função 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 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 os resultados da consulta.