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 lugar. Embora você também possa consultar o conjunto de dados diretamente, os dois métodos de consulta lidam com limites de privacidade e áreas de pesquisa:

• As funções de contagem de lugares podem retornar qualquer contagem, incluindo 0, mas aplicam uma área de pesquisa mínima de 40 x 40 metros (1.600 m²). Elas também retornam IDs de lugar, que podem ser usados para consultar informações sobre lugares específicos, e oferecem suporte à análise histórica de PDIs em snapshots mensais anteriores usando filtros de data opcionais.

• As consultas de conjuntos 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 as funções de contagem de lugares, como PLACES_COUNT_PER_H3. Ela fornece insights imediatos sobre a densidade espacial em células de grade padronizadas, retorna IDs de lugar para inspeção de informações empíricas e é criada especificamente para engenharia de atributos geoespaciais e modelos de ML.

Selecionar a função de contagem de lugares ideal

O Insights de Lugares é compatível com várias funções espaciais. Para execução otimizada de consultas, processamento paralelo e escalonabilidade em lote, recomendamos o uso das seguintes funções:

• PLACES_COUNT_PER_H3: retorna uma tabela do BigQuery com as contagens de lugares por célula H3. Essa função é recomendada para análise de densidade regional e mapas de calor coropléticos.
• PLACES_COUNT_V2: retorna uma tabela com as contagens de lugares e exemplos de IDs de lugar. Essa função aceita um parâmetro de tabela que contém as regiões 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 um 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 lugar de exemplo, categorizados por tipo de lugar. Assim como em PLACES_COUNT_V2, transmitir as geografias de entrada como um parâmetro de tabela permite que o BigQuery paralelize nativamente as interseções espaciais em grandes conjuntos de dados.
• PLACES_COUNT_CHANGE: retorna uma tabela de contagens de lugares, além de IDs de lugar adicionados e removidos entre dois meses específicos. Assim como em PLACES_COUNT_V2, transmitir as geografias de entrada como um parâmetro de tabela permite que o BigQuery paralelizar nativamente as interseções espaciais em grandes conjuntos de dados.

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

Os IDs de lugar podem ser usados com:

• API Places (nova)
• API Geocoding
• Kit de interface do Places

Observação: você pode acessar as funções de contagem de lugares para as mesmas cidades e países que tem acesso.

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 o nome personalizado em vez dos nomes de tabela padrão. Também é possível incluir o nome do projeto. Se um não for incluído, a consulta será padronizada para o projeto ativo.

Exemplo:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

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

Observação: ao usar uma função de contagem de lugares, especifique-a na cláusula FROM e omita WITH_AGGREGATION_THRESHOLD.

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

As funções de contagem de lugares aceitam 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 estavam em um mês específico, adicione o parâmetro opcional snapshot_date ao 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 suas áreas de pesquisa, conforme registrado 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 por avaliação mínima do usuário, nível de preço, status comercial e se o restaurante permite cães, usando a função PLACES_COUNT_V2.

Primeiro, use sua tabela de regiões de entrada ou prepare uma com as regiões escolhidas:

Importante: é necessário criar o conjunto de dados que contém a tabela de regiões de entrada na mesma região do conjunto de dados vinculado do Insights de Lugares. Se os locais não forem correspondentes, o BigQuery retornará um erro.

-- 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 ao redor 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
      )
);

Observação: inclua o filtro business_status para garantir que você receba a contagem de empresas OPERATIONAL. Caso contrário, a contagem vai incluir as empresas fechadas.

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 geografia de entrada personalizada my_search_areas para retornar o número de restaurantes em operação em um raio de 1.000 metros do Empire State Building e da Times Square, em 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 geografia, a contagem e uma amostra de IDs de lugar.

O exemplo a seguir usa a função PLACES_COUNT_V2 para filtrar por IDs de marca 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 tabela brands do seu 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 conseguir os IDs de marca, use-os no filtro brand_ids, como 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"]
      )
);

Observação: os parâmetros obrigatórios e opcionais são diferentes para cada função de contagem de lugares, conforme descrito em filtros.

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 seus dados do BigQuery. O BigQuery é compatível com várias ferramentas de visualização de dados do Google e de terceiros que você pode usar para analisar os resultados das suas funções nos dados do Insights de Lugares.

Para ver um exemplo de como visualizar os 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ó são compatíveis com insights de COUNT.
• É necessária uma área de pesquisa mínima de 40,0 metros por 40,0 metros (1.600 m²).
• Limite de tamanho de entrada do parâmetro:o objeto JSON transmitido como parâmetro para as funções é limitado a 1 MB. O impacto desse limite depende da versão da função:
  • Para funções da 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 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 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 geografia. Isso pode limitar o número de regiões 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 os países que você assinou. Consulte Configurar o Insights de Lugares para acessar o 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.