Introdução aos Insights do Google Places

As funções de contagem de lugares são consultas SQL predefinidas que são executadas no BigQuery e são a maneira recomendada de consultar o conjunto de dados do Insights de Lugares para recuperar contagens exatas e IDs de lugares. Embora também seja possível consultar o conjunto de dados diretamente, os dois métodos de consulta processam limites de privacidade e áreas de pesquisa:

  • As funções de contagem de lugares podem retornar qualquer contagem, incluindo 0, mas impõem uma área de pesquisa mínima de 40,0 metros por 40,0 metros (1.600 m2) (40,0 metros por 40,0 metros / 1.600 m²). As funções também retornam IDs de lugares, que podem ser usados para pesquisar informações sobre lugares individuais, e oferecem suporte à análise histórica de PDI em snapshots mensais anteriores usando filtros de data opcionais.

  • As consultas de conjunto de dados de lugares só podem retornar contagens de 5 ou mais (omitindo contagens baixas de 0 a 4 para preservar a privacidade diferencial), mas não impõem limitações ao tamanho da área de pesquisa.

A menos que você precise realizar análises espaciais complexas, recomendamos começar com funções de contagem de lugares, como PLACES_COUNT_PER_H3. Ela fornece insights imediatos de densidade espacial em células de grade padronizadas, retorna IDs de lugares para inspeção de verdade básica e é criada especificamente para engenharia de recursos geoespaciais e modelos de ML.

Selecionar a função de contagem de lugares ideal

O Insights de Lugares oferece suporte a várias funções espaciais. Para execução de consultas otimizada, processamento paralelo e escalonabilidade em lote, recomendamos o uso das seguintes funções:

  • PLACES_COUNT_PER_H3: retorna uma tabela do BigQuery de contagens de lugares por célula H3. Essa função é recomendada para análise de densidade regional e mapa de calor coroplético.
  • PLACES_COUNT_V2: Retorna uma tabela que contém contagens de lugares e IDs de lugares de amostra. Essa função aceita um parâmetro de tabela que contém suas regiões geográficas de entrada. Ao transmitir uma tabela inteira diretamente, o mecanismo de execução do BigQuery pode distribuir a carga de trabalho e processar interseções espaciais em paralelo, permitindo o processamento em lote altamente eficiente para análises em grande escala.
  • PLACES_COUNT_PER_TYPE_V2: Retorna uma tabela de contagens de lugares e IDs de lugares de amostra, categorizados por tipo de lugar. Semelhante a PLACES_COUNT_V2, transmitir suas regiões geográficas de entrada como um parâmetro de tabela permite que o BigQuery paralelise nativamente as interseções espaciais em conjuntos de dados grandes.
  • PLACES_COUNT_CHANGE: retorna uma tabela de contagens de lugares, além de IDs de lugares adicionados e removidos entre dois meses especificados. Semelhante a PLACES_COUNT_V2, transmitir suas regiões geográficas de entrada como um parâmetro de tabela permite que o BigQuery paralelise nativamente as interseções espaciais em conjuntos de dados grandes.

Além das contagens de lugares, essas funções também retornam até 250 IDs de lugares por elemento da resposta.

Os IDs de lugares podem ser usados com:

Executar consultas com funções de contagem de lugares

Use o seguinte formato para chamar as funções: [project name (optional)].[table name].[function name].

Se você mudou o nome do conjunto de dados vinculado ao configurar o Insights de Lugares, use seu nome personalizado em vez dos nomes de tabela padrão. Você também pode incluir o nome do projeto. Se um não for incluído, a consulta será definida como padrão para o projeto ativo.

Exemplo:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

Use a JSON_OBJECT para transmitir argumentos para a função.

Filtrar resultados de consultas usando parâmetros que diferenciam maiúsculas de minúsculas

As funções de contagem de lugares oferecem suporte a muitos filtros para refinar sua pesquisa. Esses parâmetros (por exemplo, price_level ou types) diferenciam maiúsculas de minúsculas e precisam corresponder exatamente aos nomes dos parâmetros. Para uma lista completa de opções, consulte a referência de parâmetros de filtro.

Consultar snapshots históricos com snapshot_date

Por padrão, as funções de contagem de lugares consultam o snapshot de dados mais recente disponível. Para analisar os dados de lugares como eles existiam durante um mês específico, adicione o parâmetro opcional snapshot_date ao seu JSON_OBJECT.

  • Formato: YYYY-MM (por exemplo, '2026-07').
  • Padrão:se omitido, a função consulta automaticamente o snapshot mais recente.

O exemplo a seguir consulta as contagens de restaurantes nas áreas de pesquisa registradas no snapshot de julho de 2026:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07' -- Optional historical snapshot month
  )
);

No próximo exemplo, você aplica filtros para limitar a pesquisa pela classificação mínima do usuário, nível de preço, status da empresa e se o restaurante permite cães, usando a função PLACES_COUNT_V2.

Primeiro, use a tabela de regiões geográficas de entrada ou prepare uma com as regiões geográficas escolhidas:

-- Create a table for the input geographies
CREATE TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas` AS (
  SELECT
    '1' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9857, 40.7484) AS geo -- Empire State Building
  UNION ALL
  SELECT
    '2' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9851, 40.7580) AS geo -- Times Square
);

Em seguida, chame PLACES_COUNT_V2 com a tabela e o objeto JSON que contém os filtros. O raio de pesquisa está incluído nos filtros JSON e será aplicado em torno de cada ponto na tabela my_search_areas.

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters around each point in 'geo'
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'min_rating', 1.3,
      'price_level', ['PRICE_LEVEL_INEXPENSIVE', 'PRICE_LEVEL_MODERATE'],
      'allows_dogs', TRUE
      )
);

Exemplo: consultar contagens de restaurantes e locais de marcas com PLACES_COUNT_V2

O exemplo a seguir usa a função PLACES_COUNT_V2 com a tabela de regiões geográficas de entrada personalizada my_search_areas para retornar o número de restaurantes operacionais em um raio de 1.000 metros do Empire State Building e da Times Square na cidade de Nova York em julho de 2026:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07'
      )
);

A resposta é uma tabela do BigQuery que contém o geo_id, a região geográfica, a contagem e uma amostra de IDs de lugares.

Resultados da função "Contagem de lugares" na cidade de Nova York.

O exemplo a seguir usa a função PLACES_COUNT_V2 para filtrar por IDs de marcas específicos. Neste exemplo, filtramos os locais do Starbucks usando o ID da marca "1413758728321880760".

Para encontrar os IDs das marcas que você quer filtrar, consulte a brands tabela do conjunto de dados (por exemplo, places_insights___us.brands). Para mais informações sobre o conjunto de dados de marcas, consulte Escrever uma consulta usando dados de marcas.

Por exemplo, para encontrar o ID da marca "Starbucks":

SELECT id, name
FROM `PROJECT_NAME.places_insights___us.brands`
WHERE name = "Starbucks"

Depois de receber os IDs das marcas, você pode usá-los no filtro brand_ids, conforme mostrado na consulta a seguir:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'brand_ids', ["1413758728321880760"]
      )
);

Visualizar a saída da consulta com as ferramentas do Google Cloud

As ferramentas de análise e Business Intelligence ajudam você a descobrir insights dos dados do BigQuery. O BigQuery oferece suporte a várias ferramentas de visualização de dados do Google e de terceiros que podem ser usadas para analisar os resultados das funções nos dados do Insights de Lugares.

Para um exemplo de visualização dos resultados de uma função, consulte Visualizar resultados na referência PLACES_COUNT_PER_H3. Para mais informações sobre como visualizar os resultados do Insights de Lugares, consulte Visualizar resultados de consultas.

Limitações e requisitos de funções

As funções de contagem de lugares têm as seguintes limitações e requisitos:

  • As funções só oferecem suporte a insights COUNT.
  • É necessária uma área de pesquisa mínima de 40,0 metros por 40,0 metros (1.600 m2) (40,0 metros por 40,0 metros / 1.600 m²).
  • Limite de tamanho da entrada de parâmetros:o objeto JSON transmitido como um parâmetro para as funções é limitado a 1 MB. O impacto desse limite depende da versão da função:
    • Para funções V2 (PLACES_COUNT_V2, PLACES_COUNT_PER_TYPE_V2, PLACES_COUNT_CHANGE), esse limite se aplica apenas ao objeto JSON de filtros. Como as regiões geográficas são fornecidas separadamente usando um parâmetro de tabela, essas funções podem ser escalonadas para um número muito maior de regiões geográficas de entrada sem atingir o limite de tamanho do JSON.
    • Para PLACES_COUNT_PER_H3, PLACES_COUNT, PLACES_COUNT_PER_TYPE, e PLACES_COUNT_PER_GEO, esse limite se aplica a todo o objeto JSON, incluindo todas as definições de região geográfica. Isso pode limitar o número de regiões geográficas que podem ser processadas em uma única chamada.
  • Não há suporte para filtragem por ID de lugar ou componente de endereço.
  • Só é possível acessar as funções de contagem de lugares para as cidades e países que você assinou. Consulte Configurar o Insights de Lugares para acesso ao conjunto de dados.
  • Os parâmetros de filtro (por exemplo, geography ou types) diferenciam maiúsculas de minúsculas e precisam corresponder exatamente aos nomes dos parâmetros. Caso contrário, a consulta vai falhar.