> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ja/data/movement/llms.txt)

# Data format

Mapbox Movement data are aggregations of movement activity for a given time span and geographic area. This guide describes the different geographic areas available, along with the schema for the various time span options.

To use Mapbox Movement, you must specify both the desired Geo aggregation and time span.

## Geographic Areas

Spatially, activity can be aggregated into tiles, or into select boundary types from in the Mapbox Boundaries dataset (counties, states, etc).

### Tiles

Mapbox Movement Data can be aggregated into geographic quadrangles known as tiles. Data are available at zoom level 18, where each tile is roughly the size of a city block.

In the dataset, the `bounds` field provides the outer corner coordinates of each tile, while the `xlat` and `xlon` fields show the centroid of each quadkey.

Tiles are referenced using a numeric **quadkey** which describes the tile's zoom level and location.

#### Understanding Quadkeys

To do additional geospatial manipulation on quadkeys, you can use the [mercantile library](https://github.com/mapbox/mercantile). The conversion is necessary only if there is a need to convert CSV filenames to geographical regions, since each line item is already converted to `longitude, latitude` coordinates. You can also use the [What the Tile interactive tool](https://labs.mapbox.com/what-the-tile/) to visualize the quadkey locations.

### Mapbox Boundaries

For Movement data joined to [Mapbox Boundaries](https://www.mapbox.com/boundaries#coverage-map), the data set contains only the code of the corresponding area in the `geography` field. This is the last five characters of the ID for counties, and the last three characters of the ID for states is the region's [FIPS code](https://en.wikipedia.org/wiki/FIPS_county_code). You can also request that additional Mapbox Boundaries files be provided with a mapping between regional codes and corresponding polygon shapes, coordinates, and surface areas.

### Normalization

The [activity index](https://docs.mapbox.com/ja/data/movement/guides/activity-index/) is not normalized by area or population density, so larger and denser counties will show higher activity levels. We recommend running additional normalization if the purpose of the analysis is to compare counties or states to each other.

## Time Span Data Schema

Mapbox Movement datasets are available in two different time span types: [**Daily**](#daily-data) and [**Monthly**](#monthly-data). Multi-month aggregations are also available upon request.

The schema of these two time span types and example values for each field are defined below.

### Daily Data

Device activity is aggregated every 24 hours and generated daily, which allows for frequent updates to reflect immediate changes in activity levels.

<table><thead><tr><th>Field</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>geography</code></td><td><em>For tile aggregation:</em><br>Z18 quadkey ID<br><br><em>For Mapbox Boundary polygons:</em><br>County ID<br>State ID</td><td>032001323000312110<br><br><br>212097<br>147</td></tr><tr><td><code>xlon</code></td><td>Longitude of the center of the bounded area <em>(tile only)</em></td><td>-122.428207397461</td></tr><tr><td><code>xlat</code></td><td>Latitude of the center of the bounded area <em>(tile only)</em></td><td>47.6880413955171</td></tr><tr><td><code>bounds</code></td><td>The lower left and upper right corners of the bounded area <em>(tile only)</em></td><td>-122.42889404296875, 47.68757916850813, -122.42752075195312, 47.68850362252605</td></tr><tr><td><code>activity_index_total</code></td><td>Normalized activity factor (for all activity types)</td><td>0.069267</td></tr><tr><td><code>agg_day_period</code></td><td>The date, in local time</td><td>2020-01-01</td></tr></tbody></table>

### Monthly Data

Device activity is aggregated over a one-month time window, which allows for periodic updates to reflect changes in typical hourly activity patterns. Multi-month aggregations may be provided for improved coverage and consistency (3-month, 6-month, and 12-month).

<table><thead><tr><th>Field</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>geography</code></td><td><em>For tile aggregation:</em><br>Z18 quadkey ID</td><td>032001323000312110</td></tr><tr><td><code>xlon</code></td><td>Longitude of the center of the bounded area <em>(tile only)</em></td><td>-122.428207397461</td></tr><tr><td><code>xlat</code></td><td>Latitude of the center of the bounded area <em>(tile only)</em></td><td>47.6880413955171</td></tr><tr><td><code>bounds</code></td><td>The lower left and upper right corners of the bounded area <em>(tile only)</em></td><td>-122.42889404296875, 47.68757916850813, -122.42752075195312, 47.68850362252605</td></tr><tr><td><code>activity_index_total</code></td><td>Normalized activity factor (for all activity types)</td><td>0.069267</td></tr><tr><td><code>agg_day_period</code></td><td><em>For seven-day:</em><br>An integer that describes the day of the week, starting with <code>0</code> for Monday<br><br><em>For weekday/weekend:</em><br>An integer that describes whether the day is a weekday or a weekend</td><td><code>0</code> for Monday, <code>1</code> for Tuesday, <code>6</code> for Sunday<br><br><br><br><code>0</code> for a weekday, <code>1</code> for a weekend</td></tr><tr><td><code>agg_time_period</code></td><td><em>For hourly:</em><br>An integer between <code>0</code> and <code>23</code> that describes the hour of day<br><br><em>For 2-hour dayparts:</em><br>An integer between <code>0</code> and <code>11</code> that describes the index of the 2-hour window<br><br><em>For 4-hour dayparts:</em><br>An integer between <code>0</code> and <code>5</code> that describes the index of the 4-hour window</td><td><code>4</code> (4:00 AM)<br><code>18</code> (6:00 PM)<br><br><br><br><code>0</code> (the 00:00-1:59 time window),<br><code>11</code> (the 22:00-23:59 time window)<br><br><br><br><code>0</code> (the 00:00-3:59 time window),<br><code>5</code> (the 20:00-23:59 time window)</td></tr></tbody></table>

## Snowflake Data Share Schema

Daily or Monthly data delivered via Snowflake secure data share has a separate schema:

<table><thead><tr><th>Field</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>country</code></td><td>2 letter <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-1</a> country code</td><td>US</td></tr><tr><td><code>geography</code></td><td><em>For tile aggregation:</em><br>Z18 quadkey ID<br><br><em>For Mapbox Boundary polygons:</em><br>County ID<br>State ID</td><td>032001323000312110<br><br><br>212097<br>147</td></tr><tr><td><code>xlon</code></td><td>Longitude of the center of the bounded area <em>(tile only)</em></td><td>-122.428207397461</td></tr><tr><td><code>xlat</code></td><td>Latitude of the center of the bounded area <em>(tile only)</em></td><td>47.6880413955171</td></tr><tr><td><code>bounds</code></td><td>The lower left and upper right corners of the bounded area <em>(tile only)</em></td><td>-122.42889404296875, 47.68757916850813, -122.42752075195312, 47.68850362252605</td></tr><tr><td><code>activity_index_total</code></td><td>Normalized activity factor (for all activity types)</td><td>0.069267</td></tr><tr><td><code>agg_day_period</code></td><td><em>For seven-day:</em><br>An integer that describes the day of the week, starting with <code>0</code> for Monday<br><br><em>For weekday/weekend:</em><br>An integer that describes whether the day is a weekday or a weekend</td><td><code>0</code> for Monday, <code>1</code> for Tuesday, <code>6</code> for Sunday<br><br><br><br><code>0</code> for a weekday, <code>1</code> for a weekend</td></tr><tr><td><code>agg_time_period</code></td><td><em>For Daily Data:</em><br><code>N/A</code><br><br><em>For Monthly data:</em><br>integer between <code>0</code> and <code>23</code> that describes hour of day (based on <code>hourly_aggregation</code>)</td><td><code>N/A</code><br><br><br><br><code>3</code></td></tr><tr><td><code>data_version</code></td><td>Version # for data production.</td><td>v2.0</td></tr><tr><td><code>geo_aggregation</code></td><td><em>For tile aggregation:</em><br><code>quadkey</code><br><br><em>For Mapbox Boundary polygons:</em><br><code>adm1</code>, <code>adm2</code>, etc.<br></td><td><code>quadkey</code><br><br><br><code>adm2</code><br></td></tr><tr><td><code>daily_aggregation</code></td><td><em>For Daily data:</em><br><code>daily</code><br><br><em>For Monthly data:</em><br><code>weekday_weekend</code>, <code>day_of_week</code><br></td><td><code>daily</code><br><br><br><code>weekday_weekend</code><br></td></tr><tr><td><code>hourly_aggregation</code></td><td><em>For Daily data:</em><br><code>24</code> (24-hr daily aggregation)<br><br><em>For Monthly data:</em><br><code>{1, 2, 4}</code> integer that describes # of hours aggregated in each time bucket (hourly, 2-hour, 4-hour dayparts)</td><td><code>24</code><br><br><br><br><code>1</code><br></td></tr></tbody></table>