Consultar mudanças de PDI entre meses (PLACES_COUNT_CHANGE)

A função PLACES_COUNT_CHANGE calcula as mudanças nas contagens de lugares de interesse e recupera amostras de IDs de lugar adicionados e removidos entre dois meses específicos em várias regiões geográficas de entrada.

Assim como PLACES_COUNT_V2, essa função foi projetada para processamento em lote eficiente, aceitando um parâmetro de tabela de entrada de regiões, o que permite avaliar tendências de crescimento e mudanças comerciais em vários locais simultaneamente.

Sintaxe

SELECT *
FROM
  `PROJECT_NAME.LINKED_DATASET_NAME.PLACES_COUNT_CHANGE`(
    TABLE input_geographies,
    filters
  );

Parâmetros

• PROJECT_NAME: o nome do seu projeto do Google Cloud;
• LINKED_DATASET_NAME: o nome do conjunto de dados do BigQuery que contém as funções do Insights de Lugares (por exemplo, places_insights___us).
• input_geographies: uma tabela do BigQuery com as regiões a serem analisadas. Essa tabela precisa incluir as seguintes colunas:
  • geo_id (STRING): um identificador exclusivo para cada região geográfica.
  • geo (GEOGRAPHY): o objeto GEOGRAPHY do BigQuery que representa a área. Pode ser um ponto, um polígono ou outro tipo de geografia.
• filters (JSON): um objeto JSON com pares de chave-valor para filtrar os lugares. Consulte Parâmetros de filtro. Ela precisa incluir os seguintes filtros:
  • month1 (STRING): o primeiro mês para procurar lugares.
  • month2 (STRING): o segundo mês para procurar lugares.

Esquema da tabela de saída

A função PLACES_COUNT_CHANGE retorna uma tabela com as colunas:

Nome da coluna	Tipo de dado	Descrição
geo_id	STRING	O ID da região de entrada.
start_count	INT64	A contagem de lugares do primeiro mês.
end_count	INT64	A contagem de lugares do segundo mês.
net_change	INT64	A diferença entre end_count e start_count (end_count - start_count).
percentage_change	FLOAT64	A variação percentual do mês 1 para o mês 2.
compound_monthly_growth_rate	FLOAT64	A taxa de crescimento mensal composta do mês 1 ao mês 2.
added_count	INT64	O número de IDs de lugar de amostra em sample_added_place_ids.
removed_count	INT64	O número de IDs de lugar de amostra em sample_removed_place_ids.
sample_added_place_ids	ARRAY<STRING>	Uma lista de IDs de lugar de amostra presentes no mês 2, mas não no mês 1.
sample_removed_place_ids	ARRAY<STRING>	Uma lista de IDs de lugar de amostra presentes no mês 1, mas não no mês 2.

Os resultados são classificados por percentage_change e start_count em ordem decrescente.

Como funciona

A função processa cada linha na tabela input_geographies. Para cada objeto geo, ele conta o número de lugares que se enquadram na região geográfica (ou no geography_radius se o geo for um ponto e o raio for especificado no filters) nos dois meses especificados em month1 e month2 no filters. Usando esses lugares, ele calcula outras estatísticas úteis, como mudança percentual e taxa de crescimento mensal composta do primeiro para o segundo mês.

A contagem inclui apenas os lugares que correspondem a todas as condições definidas no objeto JSON filters.

Exemplo: calcular mudanças nas contagens de PDIs entre dois meses

Este exemplo demonstra como consultar as mudanças nas contagens de PDIs entre dois meses específicos usando os parâmetros month1 e month2, com um raio de 5.000 de um determinado ponto de geolocalização.

WITH my_locations AS (
  SELECT
    'loc_1' AS geo_id,
    ST_GEOGFROMTEXT('POINT(-122.4194 37.7749)') AS geo
  -- Add more target locations as needed...
)

SELECT *
FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_CHANGE`(
  TABLE my_locations,
  JSON_OBJECT(
    'geography_radius', 5000,
    'month1', '2026-01', -- Baseline snapshot month (YYYY-MM)
    'month2', '2026-02'  -- Comparison snapshot month (YYYY-MM)
  )
);

Analisar a saída

A consulta retorna uma tabela com uma linha para cada geografia de entrada.

• Métricas de crescimento:a saída mostra a contagem de referência (start_count: 89.560) e a contagem de comparação (end_count: 90.923), resultando em uma net_change de +1.363 lugares (+1,52% percentage_change).
• Inspeção de informações empíricas:a matriz sample_added_place_ids lista IDs de lugar específicos que foram ativados em month2 (fevereiro de 2026), enquanto sample_removed_place_ids lista IDs de lugar que não estão mais presentes.
• Conexão com a API Places:transmita esses IDs de lugar de exemplo diretamente para a API Place Details (New) para consultar nomes, endereços e atributos de lojas recém-abertas ou fechadas.