Insights sobre dinâmica da população: códigos postais dos EUA

Documentação do desenvolvedor

Descrição do produto

O PDI é um conjunto de dados de incorporações que destila dados sobre o comportamento humano e nossa interação com o ambiente em incorporações concisas e prontas para análise (ou "impressões digitais digitais") em locais específicos.

Esses embeddings capturam padrões em dados agregados, como tendências de pesquisa, de movimentação e condições ambientais (mapas, qualidade do ar, clima), fornecendo um panorama rico e específico do local sobre como as populações interagem com o ambiente ao redor. Agregadas no espaço e no tempo, essas incorporações garantem a privacidade e permitem análises espaciais e previsões detalhadas para aplicativos que vão da saúde pública à modelagem socioeconômica.

Visão geral do produto

Os encodings de dinâmica populacional são gerados usando um modelo de aprendizado de máquina criado para essa finalidade, treinado em um conjunto avançado de recursos e convertido em uma representação vetorial condensada. Esses embeddings são treinados e gerados com base em:

• Tendências de pesquisa agregadas: interesses e preocupações regionais refletidos nos dados de pesquisa.
• Dados agregados do Maps (incluindo movimentação): comodidades, serviços e empresas nas regiões, além de tendências de visitação local.
• Clima e qualidade do ar agregados: métricas relacionadas ao clima, incluindo temperatura e qualidade do ar.

Esses recursos são agregados no nível do código postal para gerar incorporações localizadas e sensíveis ao contexto que preservam a privacidade. O PDI é um conjunto de dados de série temporal contínuo, com novas partições de dados processadas e particionadas mensalmente. Os dados são atualizados e anexados à tabela até o último dia do mês civil seguinte (por exemplo, os dados de fevereiro são publicados até 31 de março).

Pré-requisitos

Para acessar as incorporações de dinâmica populacional, você precisa ter acesso. Se você não tiver acesso, entre em contato com seu representante de vendas ou de engenharia de clientes.

• Ative a API Analytics Hub no Console do Cloud.
• Ative a API BigQuery no console do Cloud.
• Ter conhecimento prático do produto BigQuery.
• Verifique se sua conta tem o papel de proprietário da assinatura do Analytics Hub (roles/analyticshub.subscriptionOwner) para realizar tarefas de assinante.
• Verifique se sua conta tem o papel de usuário do BigQuery (roles/bigquery.user) para criar conjuntos de dados.

Treinamento recomendado

Se você não tem experiência com incorporações ou BigQuery Machine Learning, recomendamos concluir os seguintes materiais de treinamento antes de começar sua análise:

• Curso intensivo de machine learning: embeddings: uma visão geral básica e rápida de como os modelos de machine learning usam embeddings para traduzir dados de alta dimensão em espaço de baixa dimensão, mantendo relações semânticas.
• Introdução à pesquisa vetorial e aos embeddings: um laboratório prático do Google Cloud Skills Boost que apresenta embeddings vetoriais, similaridade semântica e como usar embeddings no ecossistema mais amplo do Google Cloud.
• Tutoriais do BigQuery Machine Learning (BQML): como o conjunto de dados de PDI está hospedado no BigQuery, é possível treinar e executar modelos de machine learning diretamente nas incorporações usando SQL padrão, sem precisar exportar os dados.

Usar os embeddings

Entender os dados

Antes de começar a análise, revise a estrutura do esquema.

Organização do conjunto de dados

Os embeddings são organizados em tabelas separadas do BigQuery para cada país ou região de teste.

Anatomia do vetor de embedding

A coluna features é um vetor de 330 dimensões (armazenado como uma matriz REPEATED FLOAT no BigQuery). Cada seção da matriz corresponde a um indicador de dados específico extraído pelo modelo de dinâmica populacional.

Entender essa estrutura permite a remoção de atributos (por exemplo, determinar o quanto o comportamento de pesquisa prevê vendas em comparação com o clima).

Índices vetoriais	Fonte de dados	Descrição
0 a 127	Tendências de pesquisa agregadas	Captura interesses e preocupações regionais (por exemplo, pesquisas por "academia", "sintomas de gripe", "bens de luxo").
128 a 255	Mapas e movimentação	Captura o ambiente construído (PDIs como hospitais, parques, escolas) e a visitação humana para mostrar lugares de interesse.
256 a 329	Clima e qualidade do ar	Captura o contexto ambiental (temperatura, precipitação, qualidade do ar).

Colunas principais e metadados

A tabela de incorporações contém metadados espaciais e temporais que permitem análise, filtragem e interoperabilidade geoespaciais com outros serviços.

Como um único código postal pode ocasionalmente cruzar limites de área político-administrativa (como linhas de condado), os campos de área político-administrativa são fornecidos como matrizes.

• geo_id: o ID de lugar exclusivo associado a este código postal.
• geo_name: a string do código postal da região (por exemplo, '90210').
• administrative_area_level_1_names: uma lista (ARRAY<STRING>) de nomes legíveis para humanos dos limites de nível superior (por exemplo, ['California']).
• administrative_area_level_1_ids: uma lista (ARRAY<STRING>) de IDs de lugar exclusivos para os limites administrativos de nível superior que este código postal cruza (por exemplo, estado ou província).
• administrative_area_level_2_names: uma lista (ARRAY<STRING>) de nomes legíveis para os limites secundários (por exemplo, ['Los Angeles County']).
• administrative_area_level_2_ids: uma lista (ARRAY<STRING>) de IDs de lugar exclusivos para os limites administrativos secundários que este código postal cruza (por exemplo, condado ou distrito).
• features: o vetor de embedding principal de 330 dimensões, armazenado nativamente como um ARRAY<FLOAT64>. Para carregar isso no Pandas usando Python, é necessário nivelar ou converter em uma matriz NumPy.
• snapshot_date: um DATE formatado como YYYY-MM-DD, padronizado para usar apenas o primeiro dia do mês. Representa a faixa de tempo mensal específica em que os recursos de entrada foram agregados para gerar os dados de embeddings. Por exemplo, os dados de abril de 2026 serão formatados como 2026-04-01.

Dica: usar IDs de lugar: a inclusão de geo_id e dos IDs de limite administrativo usa IDs de lugar de forma nativa. Isso permite unir esse conjunto de dados às APIs Places ou API Geocoding usando um ID de lugar padrão, evitando totalmente a correspondência aproximada de strings de nomes geográficos.

Preparar dados de informações empíricas

Para usar as incorporações de dinâmica populacional, seus dados de referência local precisam ser agregados a um limite geográfico compatível (códigos postais).

Opção 1: incorporar embeddings a um modelo atual

1. Preparar informações empíricas baseadas em modelo: use os embeddings como covariáveis geoespaciais para aprimorar um modelo atual.
2. Treinar um modelo de correção de erros: melhore um modelo atual integrando os embeddings a um modelo que usa a saída do modelo original, o valor esperado ou a verdade fundamental e os embeddings para aprender um novo modelo de correção de erros.

Opção 2: ajuste para casos de uso específicos

1. Escolha um tipo de modelo de previsão: qualquer modelo, como GBDT, MLP ou linear, pode ser usado para previsões.
2. Usar incorporações para previsão: use incorporações de dinâmica populacional como recursos de entrada, junto com outros dados contextuais, para melhorar a acurácia da previsão.

Snippets de código de início rápido

Use esses snippets para verificar seu acesso e entender o formato dos dados.

Observação: se você os mudou durante a configuração, substitua population_dynamics___us___domestic.v1_postal_code pelo nome real do projeto, do conjunto de dados e da tabela de destino (por exemplo, your-project.your_dataset.your_embeddings_table).

1. SQL: buscar embeddings de um mês específico

Como o PDI é um conjunto de dados de série temporal, geralmente é recomendável filtrar por snapshot_date para não retornar códigos postais duplicados em vários meses. O dia precisa ser sempre definido como -01.

SELECT
  snapshot_date,
  geo_name AS postal_code,
  geo_id AS place_id,
  features -- The 330-dim vector
FROM
  `your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table`
WHERE
  snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
LIMIT 10;

2. SQL: filtragem por área administrativa (desencapsulamento de matrizes)

Como os CEPs podem abranger vários limites administrativos, os campos administrative_area_* são armazenados como matrizes. Para filtrar todos os códigos postais de um estado específico (por exemplo, "Califórnia"), use a função UNNEST() do BigQuery.

SELECT
  snapshot_date,
  geo_name AS postal_code,
  admin1_name
FROM
  your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table,
  UNNEST(administrative_area_level_1_names) AS admin1_name
WHERE
  -- On or after October 2025
  snapshot_date >= '2025-10-01' -- You must use the first of the month ('-01')
  AND admin1_name = 'California'
LIMIT 10;

3. SQL: como encontrar locais semelhantes

Essa consulta identifica locais comportamentalmente semelhantes sem exigir dados externos. Ela usa a função ML.DISTANCE para calcular a similaridade do cosseno e retorna as principais correspondências para um código postal de destino.

WITH TargetLocation AS (
  SELECT features AS target_vector
  FROM `your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table`
  WHERE snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
    AND geo_name = '90210' -- Replace with your target postal code
  LIMIT 1
)
SELECT
  t.geo_name AS postal_code,
  -- Calculate Similarity (1.0 is identical, 0.0 is dissimilar)
  (1 - ML.DISTANCE(t.features, p.target_vector, 'COSINE')) AS similarity_score
FROM
  `your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table` t,
  TargetLocation p
WHERE
  t.snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
  AND t.geo_name != '90210' -- Exclude the target itself
ORDER BY
  similarity_score DESC
LIMIT 20;

4. SQL: como unir dados de clientes

Este exemplo demonstra como enriquecer seus próprios dados internos (por exemplo, uma tabela de performance da loja) com embeddings comportamentais ao fazer uma junção com base no CEP.

SELECT
  store.store_id,
  store.postal_code,
  store.total_revenue,
  embeddings.features AS pdi_vector
FROM
  `your-project.internal_data.store_performance` AS store
JOIN
  `your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table` AS embeddings
ON
  store.postal_code = embeddings.geo_name
WHERE
  embeddings.snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')

5. Python: carregamento de dados para machine learning

Os embeddings são armazenados como matrizes do BigQuery. Para usá-las em bibliotecas de ML, é necessário converter a coluna em uma matriz NumPy.

from google.cloud import bigquery
import numpy as np
import pandas as pd

client = bigquery.Client()

query = """
SELECT
  geo_name,
  features -- Returns as a list of floats
FROM
  `your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table`
WHERE
  snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
LIMIT 1000
"""

# 1. Load data into DataFrame
df = client.query(query).to_dataframe()

# 2. Convert the 'features' column (Series of Lists) into a Matrix (2D Array)
X_matrix = np.stack(df['features'].values)

print(f"Data Loaded. Matrix Shape: {X_matrix.shape}")
# Output: Data Loaded. Matrix Shape: (1000, 330)

Perguntas frequentes

Posso acessar os dados de entrada brutos (por exemplo, consultas de pesquisa específicas ou rastros de mobilidade)?

Não. Os encodings de dinâmica populacional são gerados com base em sinais agregados que preservam a privacidade. Para garantir a privacidade do usuário, não fornecemos rastreamentos específicos, históricos de pesquisa individuais ou padrões de movimento brutos. Os embeddings fornecem uma representação latente desses comportamentos, otimizada para modelagem e previsão, em vez de análises brutas.

Como você seleciona os termos de pesquisa usados para gerar os embeddings?

Usamos entidades do Mapa de informações (KG, na sigla em inglês) em vez de consultas de pesquisa brutas. Por exemplo, consultas como "namorado da taylor swift" e "tight end do kc" seriam mapeadas para a mesma entidade do KG ("Travis Kelce"). Essa abordagem é independente de idioma, captura categorias semânticas mais amplas e melhora significativamente a privacidade.

As dimensões do vetor são interpretáveis? Por exemplo, a dimensão 5 é "Café"?

Não, os vetores são representações latentes. Como os recursos são aprendidos pelo modelo de machine learning, não há um mapeamento semântico simples ou uma tradução individual de um índice de vetor final para uma entrada de origem específica. Sabemos quais blocos de índices derivam de quais conjuntos de dados (por exemplo, os índices de 0 a 127 representam o Google Trends), mas um índice específico, como o 5, não é mapeado para uma única palavra-chave. Em vez disso, ele representa um recurso complexo e abstrato aprendido pelo modelo.

O conjunto de dados inclui limites de polígonos (Shapefiles)?

Não. O conjunto de dados fornece códigos postais (geo_name) e os IDs de lugar (geo_id) associados, mas não inclui geometrias de polígonos brutos (como WKT).

Dependendo do seu caso de uso, recomendamos as seguintes abordagens:

• Para visualização no Google Maps: use os IDs de lugar fornecidos em geo_id para estilizar e renderizar os limites diretamente em um mapa usando estilo baseado em dados. Embora sejam ideais para exibição visual, não podem ser exportados como arquivos de geometria bruta.
• Para junções e análises espaciais: se você precisar de polígonos espaciais brutos, recomendamos unir esse conjunto de dados a conjuntos de dados de limites públicos (como os disponíveis nos conjuntos de dados públicos do BigQuery) usando o código postal geo_name.

Qual é o período do conjunto de dados de embeddings?

As incorporações de PDI são atualizadas mensalmente com cada novo mês anexado ao conjunto de dados. Os dados são representados usando a coluna snapshot_date (formatada como YYYY-MM-DD), fornecendo um valor de referência estável que reflete a impressão digital comportamental e física de um local para determinado mês.