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 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 |
| visit_length_p50 | int | Median length of visit to location | 50.38 |
| visit_length_avg | float | Average length of visit to location | 82.13 |
| quick_stop_visits_sum | int | Number of visitors staying 10 minutes or shorter | 93 |
| quick_stop_visits_p50 | int | Median of visitors staying 10 minutes or shorter | 53 |
| short_stay_visits_sum | int | Number of visitors staying between 10 and 45 minutes | 23 |
| short_stay_visits_p50 | int | Median of visitors staying between 10 and 45 minutes | 3 |
| moderate_stay_visits_sum | int | Number of visitors staying between 45 and 90 minutes | 51 |
| moderate_stay_visits_p50 | int | Median of visitors staying between 45 and 90 minutes | 7 |
| long_stay_visits_sum | int | Number of visitors staying 90+ minutes | 65 |
| long_stay_visits_p50 | int | Median of visitors staying 90+ minutes | 9 |
Trade Area Dataset
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 (CBG) or US Zip Code Tabulation Area (ZCTA) of origin | 320030027072 or 98034 |
| 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 Dataset
| 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 |
| top_category | STRING | The label associated with the first 4 digits of the POI’s NAICS category. | Automobile Dealers |
| sub_category | STRING | The label associated with all 6 digits of the POI’s NAICS category. For POIs with a 4-digit NAICS category, this column is null | New Car Dealers |
| naics_code | STRING | 4-digit or 6-digit NAICS code describing the business. | 441110 |
| category_tags | STRING | An array of descriptive tags indicating higher-resolution category information. | [Mexican Food,Casual Dining,Lunch,Dinner] |
| latitude | STRING | Latitude coordinate of the place of interest | 36.714767 |
| longitude | STRING | Longitude coordinate of the place of interest | -121.662912 |
| 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 |
| iso_country_code | STRING | The 2 letter ISO 3166-1 alpha-2 country code. | US |
| census_code | STRING | Census block group fips ID | 010010201001 |
| open_hours | STRING | A 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_on | STRING | The 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_on | STRING | The outside year and month this POI closed in yyyy-mm format. If null, then this POI is open. | 2020-03 |
| tracking_closed_since | STRING | Indicates the year and month we started tracking "closed_on" for this POI. | 2019-07 |
| store_id | STRING | The unique ID associated with the store as provided and maintained by the store/brand itself. | 36558 |
| parent_safegraph_brand_id | STRING | If 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_class | STRING | The 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_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 Locations context
Since custom locations are provided by the user, we do not have additional context to provide.