## Understand the Data

While the embeddings are available for multiple countries, the schema remains
consistent across all datasets. The embeddings are organized into separate
BigQuery listings for each country.

## Anatomy of the Embedding Vector

The `features` column is a 330-dimensional vector (stored as a `REPEATED FLOAT`
array in BigQuery). Each section of the array corresponds to a specific data
signal extracted by the Population Dynamics model.

Understanding this structure allows for feature ablation (for instance,
determining how much search behavior predicts sales as compared to weather).

| Vector indices | Data source | Description |
|---|---|---|
| 0 -- 127 | Aggregated Search Trends | Captures aggregated and anonymized consumer interest at the regional level (for instance, relative regional search interest in 'home improvement,' 'running shoes,' or 'electric vehicles'). Raw queries are never exposed. |
| 128 -- 255 | Maps and Busyness | Captures the built environment (POIs like restaurants, parks, schools) and aggregated and anonymized busyness at public establishments. |
| 256 -- 329 | Weather and Air Quality | Captures environmental context (such as Temperature, Precipitation, AQI, Wind). |

## Key columns and metadata

The embeddings table contains spatial metadata enabling geospatial analysis,
filtering, and interoperability with other Google Maps Platform services.

- `geo_id`: The primary identifier for the region. For [S2
  cell](https://s2geometry.io/) datasets, this is the S2 cell token represented as a hexadecimal string (for instance, `'80ead45'`). Use this as your primary join key.
- `geo_name`: The human-readable name for the region. Note: For S2 grid datasets, mathematical cells don't have standard names, so this column will contain the exact same token as `geo_id`. This is by design to maintain a consistent column structure across all Population Dynamics offerings.
- `administrative_area_level_1_id`: The unique Google Maps Place ID for the top-level administrative boundary (for instance, State or Province).
- `administrative_area_level_1_name`: The human-readable name for the top-level boundary (for instance, `'California'`).
- `administrative_area_level_2_id`: The unique Google Maps Place ID for the secondary administrative boundary (for instance, County or District).
- `administrative_area_level_2_name`: The human-readable name for the secondary boundary (for instance, `'Tulare County'`).
- `features`: The core 330-dimensional embedding vector, stored natively as an `ARRAY<FLOAT64>`. Loading this into the Pandas Python library requires flattening or converting to a NumPy matrix.

> [!TIP]
> **Tip:** Use [Place IDs](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt) (`administrative_area_level_1_id` and `administrative_area_level_2_id`) when joining your data with the embeddings. This ensures higher accuracy and precision instead of relying on fuzzy string matching of geographic names which can be error prone.

## Frequently asked questions (FAQ)

### Can I access the raw input data (for example, specific search queries or mobility traces)?

No. The Population Dynamics Insights embeddings are generated from aggregated,
privacy-preserving signals. To ensure user privacy, we don't provide specific
user traces, individual search histories, or raw movement patterns. The
embeddings provide a latent representation of these behaviors, optimized for
modeling and prediction, rather than raw analytics.

### Are the vector dimensions interpretable (for example, is Dimension 5 "Coffee")?

The vectors are latent representations, meaning they capture abstract patterns
rather than specific, human-readable labels. While we know that indices 0--127
derive from Search Trends, a specific index (like index 5) does not map
one-to-one to a single keyword like "Coffee." Instead, it represents a complex
feature of search behavior learned by the model.

### Does the dataset include polygon boundaries (Shapefiles)?

The dataset provides S2 cell tokens (`geo_id`) and Place IDs for geographic
identifiers (such as admin 1 and admin 2 regions), but it does not include raw
polygon geometry (WKT/Shapefiles) for the S2 cell regions. Omitting raw
geometries prevents storage bloat and reduces BigQuery scanning costs for ML
pipelines that only require feature vectors. Furthermore, joining on S2 string
tokens is significantly faster and more computationally efficient than executing
spatial polygon intersections.

- **For Point Coordinates:** To join point data (such as POI locations or store centroids) with Population Dynamics Insights, convert lat/lng coordinates into S2 Level 12 cell tokens using `S2_CELLIDFROMPOINT` combined with `ST_GEOGPOINT` (see [Convert point coordinates to S2 Level 12 hex
  tokens](https://developers.google.com/maps/documentation/population-dynamics-insights/use-embeddings#convert_point_coordinates_to_s2_level_12_hex_tokens)).
- **For Area Boundaries:** If you need to intersect custom boundaries with Population Dynamics Insights, we recommend converting your custom polygons into covering S2 Level 12 cell tokens using `S2_COVERINGCELLIDS` (see [Generate covering S2 Level 12 cell tokens for a
  polygon](https://developers.google.com/maps/documentation/population-dynamics-insights/use-embeddings#generate_covering_s2_level_12_cell_tokens_for_a_polygon)) or joining this dataset with public boundary datasets available in BigQuery Public Data.
- **For Visualization and Geometry Conversion:** BigQuery's built-in geography functions perform one-way conversion (Geometry → S2 Cell ID). To convert S2 cell tokens into polygon geometries for mapping or GIS tools, you can use client-side libraries, like Python's [`s2sphere`](https://pypi.org/project/s2sphere/). For code samples and instructions, see [Get S2 cell geometry from an S2
  Level 12 hex
  token](https://developers.google.com/maps/documentation/population-dynamics-insights/use-embeddings#get_s2_cell_geometry_from_an_s2_level_12_hex_token).