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
visit_length_p50intMedian length of visit to location50.38
visit_length_avgfloatAverage length of visit to location82.13
quick_stop_visits_sumintNumber of visitors staying 10 minutes or shorter93
quick_stop_visits_p50intMedian of visitors staying 10 minutes or shorter53
short_stay_visits_sumintNumber of visitors staying between 10 and 45 minutes23
short_stay_visits_p50intMedian of visitors staying between 10 and 45 minutes3
moderate_stay_visits_sumintNumber of visitors staying between 45 and 90 minutes51
moderate_stay_visits_p50intMedian of visitors staying between 45 and 90 minutes7
long_stay_visits_sumintNumber of visitors staying 90+ minutes65
long_stay_visits_p50intMedian of visitors staying 90+ minutes9

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
top_categorySTRINGThe label associated with the first 4 digits of the POI’s NAICS category.Automobile Dealers
sub_categorySTRINGThe label associated with all 6 digits of the POI’s NAICS category. For POIs with a 4-digit NAICS category, this column is nullNew Car Dealers
naics_codeSTRING4-digit or 6-digit NAICS code describing the business.441110
category_tagsSTRINGAn array of descriptive tags indicating higher-resolution category information.[Mexican Food,Casual Dining,Lunch,Dinner]
latitudeSTRINGLatitude coordinate of the place of interest36.714767
longitudeSTRINGLongitude coordinate of the place of interest-121.662912
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
iso_country_codeSTRINGThe 2 letter ISO 3166-1 alpha-2 country code.US
census_codeSTRINGCensus block group fips ID010010201001
open_hoursSTRINGA JSON string with days as keys and opening & closing times (in the POI's local time) as values.{ "Mon": [["8:00", "22:00"]], "Tue": [["8:00", "13:00"], ["18:00", "24:00"]], "Wed": [["0:00", "2:00"]], "Thu": [["0:00", "24:00"]], "Fri": [["23:00", "24:00"]], "Sat": [["0:00", "3:00"], ["15:00", "22:30"]], "Sun": [] }
opened_onSTRINGThe outside year and month this POI opened in yyyy-mm format. If null, then we do not have enough metadata to determine an open date.2019-10
closed_onSTRINGThe outside year and month this POI closed in yyyy-mm format. If null, then this POI is open.2020-03
tracking_closed_sinceSTRINGIndicates the year and month we started tracking "closed_on" for this POI.2019-07
store_idSTRINGThe unique ID associated with the store as provided and maintained by the store/brand itself.36558
parent_safegraph_brand_idSTRINGIf this brand has a parent, this will list the ID of the parent brand. If this brand has no parent, this will be null.SG_BRAND_8310c2e3461b8b5a
polygon_classSTRINGThe classification of the polygon: 1) OWNED_POLYGON: only one POI maps to this distinct polygon. 2) SHARED_POLYGON: at least two POIs share the same polygon.OWNED_POLYGON
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.