Skip to main content

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 location details inline. See the different Location schemas here.

Foot-traffic Dataset

Foot-traffic describes the median estimated daily visitors to the location aggregated on a weekly or monthly basis.

Field nameTypeDescriptionExample
location_idstringThe geographical identification of a value in the data set.ed5ca2fd-69d9-4e6a-ae59-abeb39b13fb8
observation_start_datestring (yyyy-mm-dd)The start date for the period this observation took place.2023-02-05
observation_end_datestring (yyyy-mm-dd)The end date for the period this observation took place.2023-02-11
visits_sumintEstimated sum of unique people per day at the location during the observation period. Includes all people even residents and workers.2,772
visits_p50intEstimated median of unique people per day at the location during the observation period. Includes all people even residents and workers.409

Trade Area Dataset

Trade Area describes the origin of visitors from their Home or Work location to the location on a quarterly basis.

Field nameTypeDescriptionExample
location_idstringThe geographical identification of a value in the data set.ed5ca2fd-69d9-4e6a-ae59-abeb39b13fb8
trade_area_location_idstringID of US Census block groups (CBG) or US Zip Code Tabulation Area (ZCTA) of origin320030027072 or 98034
trade_area_typestringName of dimension describing if the trade area describes the HOME or WORK locationHOME
observation_start_datestring (yyyy-mm-dd)The start date for the period this observation took place.2023-01-01
observation_end_datestring (yyyy-mm-dd)The end date for the period this observation took place.2023-03-31
people_fractionfloatEstimated fraction of location visitors with their home / work in the given CBG.0.28

Demographics Dataset

Field nameTypeDescriptionExample
location_idstringThe geographical identification of a value in the data set.ed5ca2fd-69d9-4e6a-ae59-abeb39b13fb8
observation_start_datestring (yyyy-mm-dd)The start date for the period this observation took place.2023-02-05
observation_end_datestring (yyyy-mm-dd)The end date for the period this observation took place.2023-02-11
people_fraction_age_18_29floatEstimated fraction of visitors within this age group.0.182
people_fraction_age_30_39floatEstimated fraction of visitors within this age group.0.182
people_fraction_age_40_49floatEstimated fraction of visitors within this age group.0.182
people_fraction_age_50_59floatEstimated fraction of visitors within this age group.0.182
people_fraction_age_60_69floatEstimated fraction of visitors within this age group.0.182
people_fraction_age_70_79floatEstimated fraction of visitors within this age group.0.182
people_fraction_age_80_and_abovefloatEstimated fraction of visitors within this age group.0.182
people_fraction_education_high_schoolfloatEstimated fraction of visitors with this education level.0.182
people_fraction_education_college_without_degreefloatEstimated fraction of visitors with this education level.0.182
people_fraction_education_associatefloatEstimated fraction of visitors with this education level.0.182
people_fraction_education_bachelorfloatEstimated fraction of visitors with this education level.0.182
people_fraction_education_master_and_abovefloatEstimated fraction of visitors with this education level.0.182
people_fraction_gender_femalefloatEstimated fraction of visitors with this gender.0.182
people_fraction_gender_malefloatEstimated fraction of visitors with this gender.0.182
people_fraction_income_25k_and_lessfloatEstimated fraction of visitors within this income range.0.182
people_fraction_income_25k_50kfloatEstimated fraction of visitors within this income range.0.182
people_fraction_income_50k_75kfloatEstimated fraction of visitors within this income range.0.182
people_fraction_income_75k_100kfloatEstimated fraction of visitors within this income range.0.182
people_fraction_income_100k_125kfloatEstimated fraction of visitors within this income range.0.182
people_fraction_income_125k_and_abovefloatEstimated fraction of visitors within this income range.0.182
people_fraction_race_amerindianfloatEstimated fraction of visitors with this race.0.182
people_fraction_race_asianfloatEstimated fraction of visitors with this race.0.182
people_fraction_race_blackfloatEstimated fraction of visitors with this race.0.182
people_fraction_race_whitefloatEstimated fraction of visitors with this race.0.182
people_fraction_race_otherfloatEstimated fraction of visitors with this race.0.182
people_fraction_race_two_or_morefloatEstimated 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 nameTypeDescriptionExample
placekeySTRINGUnique and persistent ID tied to this POI. See Placekey for details on placekey design.333-333@222-333-444
parent_placekeySTRINGIf 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_nameSTRINGThe name of the place of interest.Salinas Valley Ford Lincoln
safegraph_brand_idsSTRINGUnique and consistent ID that represents this specific brand.SG_BRAND_8310c2e3461b8b5a
brandsSTRINGIf this POI is an instance of a larger brand that we have explicitly identified, this column will contain that brand name.Circle K
naics_codeSTRING4-digit or 6-digit NAICS code describing the business.441110
street_addressSTRINGStreet address of the place of interest1100 Auto Center Circle
citySTRINGThe city of the point of interestIrvine
regionSTRINGThe state, province, county, or equivalent of how "region" is understood in a given country for the place of interest.CO
postal_codeSTRINGThe postal code of the place of interest.92602
census_codeSTRINGCensus block group fips ID010010201001
polygon_confidence_scoreSTRINGModelled score estimating likelihood of accurate foot traffic prediction. Read more here.0.8

CBG locations

Field nameTypeDescriptionExample
census_block_group_idstringThe geographical identification of a value in the data set.021580001002
areaint12,721,633,137
us_state_idstringUS State FIPS Code (2 digits)02
us_statestringName of US StateAlaska
us_county_idstringUS County FIPS code (5 digits)02158
us_countystringName of US CountyKusilvak Census Area, AK
us_tract_idstringUS Census Tract FIPS code (11 digits)02158000100
us_tractstringName of US Census Tract02158000100
us_cbsa_idstringUS Core-Based Statistical Area code (5 digits)
us_cbsastringName of US Core-Based Statistical Area
us_census_block_group_idstringID of US Census Block Group FIPS code.021580001002
us_census_block_groupstringName of US Census Block Group FIPS code.021580001002

Custom Locations context

Since custom locations are provided by the user, we do not have additional context to provide.