Estadísticas de dinámica de población: códigos postales de EE.UU.

Documentación para desarrolladores

Descripción del producto

Population Dynamics Insights (PDI) es un conjunto de datos de incorporaciones que destila datos sobre el comportamiento humano y nuestra interacción con el entorno en incorporaciones concisas y listas para el análisis (o "huellas digitales") en ubicaciones específicas.

Estos embeddings capturan patrones en datos agregados, como tendencias de búsqueda, tendencias de actividad y condiciones ambientales (mapas, calidad del aire, clima), lo que proporciona una instantánea enriquecida y específica de la ubicación sobre cómo las poblaciones interactúan con su entorno. Agregados en el espacio y el tiempo, estos embeddings garantizan la privacidad y, al mismo tiempo, permiten realizar análisis y predicciones espaciales detallados para aplicaciones que van desde la salud pública hasta el modelado socioeconómico.

Descripción general del producto

Las incorporaciones de la dinámica poblacional se generan con un modelo de aprendizaje automático creado específicamente para este fin, entrenado con un amplio conjunto de atributos y convertido en una representación vectorial condensada. Estas incorporaciones se entrenan y generan a partir de lo siguiente:

• Tendencias de búsqueda agregadas: Intereses y preocupaciones regionales que se reflejan en los datos de búsqueda
• Datos agregados de Maps (incluido el nivel de actividad): Servicios, comercios y empresas en las regiones, junto con las tendencias de visitas locales
• Clima y calidad del aire agregados: Métricas relacionadas con el clima, como la temperatura y la calidad del aire

Estas características se agregan a nivel del código postal para generar incorporaciones localizadas y sensibles al contexto que preservan la privacidad. El PDI es un conjunto de datos de series temporales continuo, con nuevas segmentaciones de datos procesadas y particionadas mensualmente. Los datos se actualizan y se agregan a la tabla de datos el último día del siguiente mes calendario (por ejemplo, los datos de febrero se publican a más tardar el 31 de marzo).

Requisitos previos

Para acceder a las incorporaciones de Population Dynamics, debes obtener acceso. Si no tienes acceso, comunícate con tu representante de ventas o de ingeniería de atención al cliente.

• Habilita la API de Analytics Hub en Cloud Console.
• Habilita la API de BigQuery en la consola de Cloud.
• Tener conocimientos prácticos del producto BigQuery
• Asegúrate de que tu cuenta tenga el rol de propietario de la suscripción a Analytics Hub (roles/analyticshub.subscriptionOwner) para realizar tareas de suscriptor.
• Asegúrate de que tu cuenta tenga el rol de usuario de BigQuery (roles/bigquery.user) para crear conjuntos de datos.

Capacitación recomendada

Si es la primera vez que trabajas con incorporaciones o BigQuery Machine Learning, te recomendamos que completes los siguientes materiales de capacitación antes de comenzar tu análisis:

• Curso intensivo de aprendizaje automático: Incorporaciones: Una descripción general fundamental y rápida sobre cómo los modelos de aprendizaje automático usan las incorporaciones para traducir datos de alta dimensión a un espacio de menor dimensión y, al mismo tiempo, conservar las relaciones semánticas.
• Comienza a usar la búsqueda de vectores y los embeddings: Un lab práctico de Google Cloud Skills Boost que presenta los embeddings de vectores, la similitud semántica y cómo utilizar los embeddings dentro del ecosistema más amplio de Google Cloud
• Instructivos de BigQuery Machine Learning (BQML): Dado que el conjunto de datos de PDI está alojado en BigQuery, puedes entrenar y ejecutar modelos de aprendizaje automático directamente en las incorporaciones con SQL estándar, sin necesidad de exportar los datos.

Cómo usar los embeddings

Cómo interpretar los datos

Antes de comenzar el análisis, dedica un momento a revisar la estructura del esquema.

Organización del conjunto de datos

Las incorporaciones se organizan en tablas de BigQuery separadas para cada país o región de prueba.

Anatomía del vector de embedding

La columna features es un vector de 330 dimensiones (almacenado como un array REPEATED FLOAT en BigQuery). Cada sección del array corresponde a un indicador de datos específico que extrae el modelo de dinámica poblacional.

Comprender esta estructura permite realizar la ablación de funciones (por ejemplo, determinar cuánto predice el comportamiento de búsqueda las ventas en comparación con el clima).

Índices vectoriales	Fuente de datos	Descripción
0 a 127	Tendencias de búsqueda agregadas	Capta los intereses y las preocupaciones regionales (por ejemplo, las búsquedas de "gimnasio", "síntomas de gripe" y "artículos de lujo").
128 a 255	Mapas y nivel de actividad	Capta el entorno construido (lugares de interés como hospitales, parques y escuelas) y las visitas humanas para mostrar lugares de interés.
256 a 329	Clima y calidad del aire	Captura el contexto ambiental (temperatura, precipitaciones y calidad del aire).

Columnas clave y metadatos

La tabla de incorporaciones contiene metadatos espaciales y temporales que permiten el análisis geoespacial, el filtrado y la interoperabilidad con otros servicios.

Dado que, en ocasiones, un solo código postal puede cruzar límites administrativos (como los límites de los condados), los campos de área administrativa se proporcionan como arrays.

• geo_id: Es el ID de lugar único asociado con este código postal.
• geo_name: Es la cadena del código postal de la región (por ejemplo, '90210').
• administrative_area_level_1_names: Es una lista (ARRAY<STRING>) de nombres legibles por humanos para los límites de nivel superior (por ejemplo, ['California']).
• administrative_area_level_1_ids: Es una lista (ARRAY<STRING>) de IDs de Place únicos para los límites administrativos de nivel superior con los que se cruza este código postal (por ejemplo, estado o provincia).
• administrative_area_level_2_names: Es una lista (ARRAY<STRING>) de nombres legibles por humanos para los límites secundarios (por ejemplo, ['Los Angeles County']).
• administrative_area_level_2_ids: Es una lista (ARRAY<STRING>) de IDs de lugar únicos para los límites administrativos secundarios con los que se cruza este código postal (por ejemplo, condado o distrito).
• features: Es el vector de incorporación principal de 330 dimensiones, almacenado de forma nativa como un ARRAY<FLOAT64>. Para cargar esto en Pandas con Python, es necesario aplanar o convertir a una matriz de NumPy.
• snapshot_date: Un DATE con el formato YYYY-MM-DD, estandarizado para usar solo el primer día del mes. Representa el período mensual específico a partir del cual se agregaron las características de entrada para generar los datos de embeddings. Por ejemplo, los datos de abril de 2026 se formatearán como 2026-04-01.

Nota: Uso de IDs de lugar: La inclusión de geo_id y los IDs de límites administrativos usa de forma nativa los IDs de lugar. Esto te permite unir sin problemas este conjunto de datos con la API de Places o la API de Geocoding usando un ID de lugar estándar, lo que evita por completo la coincidencia aproximada de cadenas de nombres geográficos.

Prepara los datos de verdad fundamental

Para usar las incorporaciones de Population Dynamics, tus datos de verdad fundamental deben agregarse a un límite geográfico admitido (códigos postales).

Opción 1: Incorpora incorporaciones en un modelo existente

1. Prepara la verdad fundamental existente basada en el modelo: Usa los embeddings como covariables geoespaciales para mejorar un modelo existente.
2. Entrena un modelo de corrección de errores: Mejora un modelo existente integrando las incorporaciones en un modelo que toma el resultado del modelo original, el valor esperado o la verdad fundamental, y las incorporaciones para aprender un nuevo modelo de corrección de errores.

Opción 2: Ajusta el modelo para casos de uso específicos

1. Elige un tipo de modelo de predicción: Se puede usar cualquier modelo, como GBDT, MLP o lineal, para las predicciones.
2. Use Embeddings for Prediction: Utiliza las incorporaciones de Population Dynamics como funciones de entrada, junto con otros datos contextuales, para mejorar la precisión de la predicción.

Fragmentos de código de inicio rápido

Usa estos fragmentos para verificar tu acceso y comprender el formato de los datos.

Nota: Si los cambiaste durante la configuración, reemplaza population_dynamics___us___domestic.v1_postal_code por tu proyecto, conjunto de datos y nombre de tabla de destino reales (por ejemplo, your-project.your_dataset.your_embeddings_table).

1. SQL: Recuperación de embeddings para un mes específico

Dado que el PDI es un conjunto de datos de series temporales, por lo general, debes filtrar por snapshot_date para no devolver códigos postales duplicados en varios meses. El día siempre debe establecerse en -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: Filtrado por área administrativa (desanidación de arrays)

Dado que los códigos postales pueden abarcar varios límites administrativos, los campos administrative_area_* se almacenan como arrays. Para filtrar todos los códigos postales de un estado específico (por ejemplo, "California"), debes usar la función UNNEST() de 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: Cómo encontrar ubicaciones similares

Esta consulta identifica ubicaciones similares en cuanto al comportamiento sin necesidad de datos externos. Usa la función ML.DISTANCE para calcular la similitud del coseno y devolver las coincidencias principales para un código postal objetivo.

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: Unión de datos de clientes

En este ejemplo, se muestra cómo enriquecer tus propios datos internos (por ejemplo, una tabla de rendimiento de la tienda) con incorporaciones de comportamiento uniéndolos por código postal.

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: Carga de datos para el aprendizaje automático

Los embeddings se almacenan como arrays de BigQuery. Para usarlas en bibliotecas de AA, debes convertir la columna en una matriz de 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)

Preguntas frecuentes

¿Puedo acceder a los datos de entrada sin procesar (por ejemplo, búsquedas específicas o registros de movilidad)?

No. Los embeddings de Population Dynamics se generan a partir de indicadores agregados que preservan la privacidad. Para garantizar la privacidad del usuario, no proporcionamos registros específicos del usuario, historiales de búsqueda individuales ni patrones de movimiento sin procesar. Las incorporaciones proporcionan una representación latente de estos comportamientos, optimizada para el modelado y la predicción, en lugar de las estadísticas sin procesar.

¿Cómo seleccionan los términos de búsqueda que se usan para generar los embeddings?

Usamos entidades del Gráfico de conocimiento (KG) en lugar de búsquedas sin procesar. Por ejemplo, las búsquedas como "novio de Taylor Swift" y "ala cerrada de KC" se asignarían a la misma entidad subyacente del KG ("Travis Kelce"). Este enfoque es independiente del idioma, captura categorías semánticas más amplias y mejora significativamente la privacidad.

¿Las dimensiones del vector son interpretables (por ejemplo, la dimensión 5 es "Café")?

No, los vectores son representaciones latentes. Dado que el modelo de aprendizaje automático aprende las características, no hay una asignación semántica simple ni una traducción uno a uno de un índice de vector final a una entrada de origen específica. Si bien sabemos qué bloques de índices se derivan de qué conjuntos de datos (por ejemplo, los índices del 0 al 127 representan las tendencias de la Búsqueda), un índice específico, como el índice 5, no se asigna a una sola palabra clave. En cambio, representa una característica compleja y abstracta que aprendió el modelo.

¿El conjunto de datos incluye límites de polígonos (Shapefiles)?

No. El conjunto de datos proporciona códigos postales (geo_name) y sus IDs de lugar asociados (geo_id), pero no incluye geometrías de polígonos sin procesar (como WKT).

Según tu caso de uso, te recomendamos los siguientes enfoques:

• Para la visualización en Google Maps: Puedes usar los IDs de lugar proporcionados en geo_id para diseñar y renderizar los límites directamente en un mapa con el diseño basado en datos. Si bien estos límites son ideales para la visualización, no se pueden exportar como archivos de geometría sin procesar.
• Para uniones y análisis espaciales: Si necesitas polígonos espaciales sin procesar, te recomendamos que unas este conjunto de datos con conjuntos de datos de límites públicos (como los que están disponibles en los conjuntos de datos públicos de BigQuery) usando el código postal geo_name.

¿Cuál es el período del conjunto de datos de embeddings?

Las incorporaciones de PDI se actualizan mensualmente con cada mes nuevo que se agrega al conjunto de datos. Los datos se representan con la columna snapshot_date (con el formato YYYY-MM-DD), lo que proporciona un valor de referencia estable que refleja la huella física y de comportamiento de una ubicación para ese mes determinado.