Schema
Schemas
Each dataset consists of the relevant metrics tied to the primary keys describing location and time. Those metrics are described in more detail here.
Location details are delivered as a file/table on the side or optionally embedded on any dataset. For bulk deliveries we recommend receiving this on the side, while for smaller extracts it can be handy to receive further locations details inline. See the different Location schemas here.
Foot-traffic
Foot-traffic describes the median estimated daily visitors to the location aggregated on a weekly or monthly basis.
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | ed5ca2fd-69d9-4e6a-ae59-abeb39b13fb8 |
| observation_start_date | string (yyyy-mm-dd) | The start date for the period this observation took place. | 2023-02-05 |
| observation_end_date | string (yyyy-mm-dd) | The end date for the period this observation took place. | 2023-02-11 |
| visits_sum | int | Estimated sum of unique people per day at the location during the observation period. Includes all people even residents and workers. | 2,772 |
| visits_p50 | int | Estimated median of unique people per day at the location during the observation period. Includes all people even residents and workers. | 409 |
Trade Area
Trade Area describes the origin of visitors from their Home or Work location to the location on a quarterly basis.
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | ed5ca2fd-69d9-4e6a-ae59-abeb39b13fb8 |
| trade_area_location_id | string | ID of US Census block groups | 320030027072 |
| trade_area_type | string | Name of dimension describing if the trade area describes the HOME or WORK location | HOME |
| observation_start_date | string (yyyy-mm-dd) | The start date for the period this observation took place. | 2023-01-01 |
| observation_end_date | string (yyyy-mm-dd) | The end date for the period this observation took place. | 2023-03-31 |
| people_fraction | float | Estimated fraction of location visitors with their home / work in the given CBG. | 0.28 |
Demographics
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | ed5ca2fd-69d9-4e6a-ae59-abeb39b13fb8 |
| observation_start_date | string (yyyy-mm-dd) | The start date for the period this observation took place. | 2023-02-05 |
| observation_end_date | string (yyyy-mm-dd) | The end date for the period this observation took place. | 2023-02-11 |
| people_fraction_age_18_29 | float | Estimated fraction of visitors within this age group. | 0.182 |
| people_fraction_age_30_39 | float | Estimated fraction of visitors within this age group. | 0.182 |
| people_fraction_age_40_49 | float | Estimated fraction of visitors within this age group. | 0.182 |
| people_fraction_age_50_59 | float | Estimated fraction of visitors within this age group. | 0.182 |
| people_fraction_age_60_69 | float | Estimated fraction of visitors within this age group. | 0.182 |
| people_fraction_age_70_79 | float | Estimated fraction of visitors within this age group. | 0.182 |
| people_fraction_age_80_and_above | float | Estimated fraction of visitors within this age group. | 0.182 |
| people_fraction_education_high_school | float | Estimated fraction of visitors with this education level. | 0.182 |
| people_fraction_education_college_without_degree | float | Estimated fraction of visitors with this education level. | 0.182 |
| people_fraction_education_associate | float | Estimated fraction of visitors with this education level. | 0.182 |
| people_fraction_education_bachelor | float | Estimated fraction of visitors with this education level. | 0.182 |
| people_fraction_education_master_and_above | float | Estimated fraction of visitors with this education level. | 0.182 |
| people_fraction_gender_female | float | Estimated fraction of visitors with this gender. | 0.182 |
| people_fraction_gender_male | float | Estimated fraction of visitors with this gender. | 0.182 |
| people_fraction_income_25k_and_less | float | Estimated fraction of visitors within this income range. | 0.182 |
| people_fraction_income_25k_50k | float | Estimated fraction of visitors within this income range. | 0.182 |
| people_fraction_income_50k_75k | float | Estimated fraction of visitors within this income range. | 0.182 |
| people_fraction_income_75k_100k | float | Estimated fraction of visitors within this income range. | 0.182 |
| people_fraction_income_100k_125k | float | Estimated fraction of visitors within this income range. | 0.182 |
| people_fraction_income_125k_and_above | float | Estimated fraction of visitors within this income range. | 0.182 |
| people_fraction_race_amerindian | float | Estimated fraction of visitors with this race. | 0.182 |
| people_fraction_race_asian | float | Estimated fraction of visitors with this race. | 0.182 |
| people_fraction_race_black | float | Estimated fraction of visitors with this race. | 0.182 |
| people_fraction_race_white | float | Estimated fraction of visitors with this race. | 0.182 |
| people_fraction_race_other | float | Estimated fraction of visitors with this race. | 0.182 |
| people_fraction_race_two_or_more | float | Estimated fraction of visitors with this race. | 0.182 |
Locations Schemas
In addition to the schemas above describing the metrics, we provide optional schemas supporting contextual information of locations. Below the default options are listed.
POI locations
Below follow the standard default option for SafeGraph Places, other configurations might apply to you. Further premium fields can be discussed with your account executive.
| Field name | Type | Description | Example |
|---|---|---|---|
| placekey | STRING | Unique and persistent ID tied to this POI. See Placekey for details on placekey design. | 333-333@222-333-444 |
| parent_placekey | STRING | If place is encompassed by a larger place (e.g. mall, airport), this lists the placekey of the parent place. | 333-334@222-333-444 |
| location_name | STRING | The name of the place of interest. | Salinas Valley Ford Lincoln |
| safegraph_brand_ids | STRING | Unique and consistent ID that represents this specific brand. | SG_BRAND_8310c2e3461b8b5a |
| brands | STRING | If this POI is an instance of a larger brand that we have explicitly identified, this column will contain that brand name. | Circle K |
| naics_code | STRING | 4-digit or 6-digit NAICS code describing the business. | 441110 |
| latitude | STRING | Latitude coordinate of the place of interest. | "0.0" |
| longitude | STRING | Longitude coordinate of the place of interest. | "0.0" |
| street_address | STRING | Street address of the place of interest | 1100 Auto Center Circle |
| city | STRING | The city of the point of interest | Irvine |
| region | STRING | The state, province, county, or equivalent of how "region" is understood in a given country for the place of interest. | CO |
| postal_code | STRING | The postal code of the place of interest. | 92602 |
| census_code | STRING | Census block group fips ID | 010010201001 |
| polygon_confidence_score | STRING | Modelled score estimating likelihood of accurate foot traffic prediction. Read more here. | 0.8 |
CBG locations
| Field name | Type | Description | Example |
|---|---|---|---|
| census_block_group_id | string | The geographical identification of a value in the data set. | 021580001002 |
| area | int | 12,721,633,137 | |
| us_state_id | string | US State FIPS Code (2 digits) | 02 |
| us_state | string | Name of US State | Alaska |
| us_county_id | string | US County FIPS code (5 digits) | 02158 |
| us_county | string | Name of US County | Kusilvak Census Area, AK |
| us_tract_id | string | US Census Tract FIPS code (11 digits) | 02158000100 |
| us_tract | string | Name of US Census Tract | 02158000100 |
| us_cbsa_id | string | US Core-Based Statistical Area code (5 digits) | |
| us_cbsa | string | Name of US Core-Based Statistical Area | |
| us_census_block_group_id | string | ID of US Census Block Group FIPS code. | 021580001002 |
| us_census_block_group | string | Name of US Census Block Group FIPS code. | 021580001002 |
Custom Boundaries context
Since custom boundaries are provided by the user, we do not have additional context to provide for custom boundaries.