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.
Visitation on Predefined POIs
Foot-traffic w/Visit Length Weekly Dataset - Predefined POIs
Foot-traffic describes the median estimated daily visitors to the location aggregated on a weekly basis.
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | 222-222@3bh-26y-d35 |
| 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 |
Foot-traffic w/Visit Length Monthly Dataset - Predefined POIs
Foot-traffic describes the median estimated daily visitors to the location aggregated on a monthly basis.
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | 222-222@3bh-26y-d35 |
| observation_start_date | string (yyyy-mm-dd) | The start date for the period this observation took place. | 2019-03-01 |
| observation_end_date | string (yyyy-mm-dd) | The end date for the period this observation took place. | 2019-03-31 |
| visits_sum | int | Estimated sum of unique people per day at the location during the observation period. Includes all people even residents and workers. | 8225 |
| visits_p50 | int | Estimated median of unique people per day at the location during the observation period. Includes all people even residents and workers. | 180 |
| visit_length_p50 | int | Median length of visit to location | 45 |
| visit_length_avg | float | Average length of visit to location | 50 |
| quick_stop_visits_sum | int | Number of visitors staying 10 minutes or shorter | 174 |
| quick_stop_visits_p50 | int | Median of visitors staying 10 minutes or shorter | 6 |
| short_stay_visits_sum | int | Number of visitors staying between 10 and 45 minutes | 131 |
| short_stay_visits_p50 | int | Median of visitors staying between 10 and 45 minutes | 16 |
| moderate_stay_visits_sum | int | Number of visitors staying between 45 and 90 minutes | 254 |
| moderate_stay_visits_p50 | int | Median of visitors staying between 45 and 90 minutes | 8 |
| long_stay_visits_sum | int | Number of visitors staying 90+ minutes | 134 |
| long_stay_visits_p50 | int | Median of visitors staying 90+ minutes | 12 |
Popular Times Quarterly Dataset - Predefined POIs
Popular Times provides insights into the typical weekly visitation patterns at a location, highlighting peak and off-peak hours, delivered on a quarterly basis.
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | 222-222@627-wbk-6c5 |
| 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 |
| day_of_week | Integer | Day of week as a number (week is numbered Sunday - Saturday, 1-7) | 5 |
| day_of_week_name | String | The Given name of the day of the week (Sunday - Saturday) | Thursday |
| hour | Integer | Hour of the day as a number between (0-23) | 18 |
| hour_name | String | The hour of the day as 12 hour label | 6:00 PM |
| occupancy | Float | Prediction of how many people were staying at the location within each hour of the week | 0.6 |
Trade Area by CBG Quarterly Dataset - Predefined POIs
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. | 222-222@627-wbk-6c5 |
| trade_area_location_id | string | ID of US Census block groups (CBG) | 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 |
Trade Area by ZIP Quarterly Dataset - Predefined POIs
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. | 222-222@627-wbk-6c5 |
| trade_area_location_id | string | US Zip Code Tabulation Area (ZCTA) of origin | 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.005 |
Demographics Quarterly Dataset - Predefined POIs
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | 227-222@3bt-bzz-jd9 |
| observation_start_date | string (yyyy-mm-dd) | The start date for the period this observation took place. | 2019-04-01 |
| observation_end_date | string (yyyy-mm-dd) | The end date for the period this observation took place. | 2019-06-30 |
| people_fraction_age_18_29 | float | Estimated fraction of visitors within this age group. | 0.185 |
| people_fraction_age_30_39 | float | Estimated fraction of visitors within this age group. | 0.179 |
| people_fraction_age_40_49 | float | Estimated fraction of visitors within this age group. | 0.154 |
| people_fraction_age_50_59 | float | Estimated fraction of visitors within this age group. | 0.176 |
| people_fraction_age_60_69 | float | Estimated fraction of visitors within this age group. | 0.166 |
| people_fraction_age_70_79 | float | Estimated fraction of visitors within this age group. | 0.094 |
| people_fraction_age_80_and_above | float | Estimated fraction of visitors within this age group. | 0.046 |
| people_fraction_education_high_school | float | Estimated fraction of visitors with this education level. | 0.213 |
| people_fraction_education_college_without_degree | float | Estimated fraction of visitors with this education level. | 0.228 |
| people_fraction_education_associate | float | Estimated fraction of visitors with this education level. | 0.087 |
| people_fraction_education_bachelor | float | Estimated fraction of visitors with this education level. | 0.194 |
| people_fraction_education_master_and_above | float | Estimated fraction of visitors with this education level. | 0.082 |
| people_fraction_gender_female | float | Estimated fraction of visitors with this gender. | 0.494 |
| people_fraction_gender_male | float | Estimated fraction of visitors with this gender. | 0.506 |
| people_fraction_income_25k_and_less | float | Estimated fraction of visitors within this income range. | 0.128 |
| people_fraction_income_25k_50k | float | Estimated fraction of visitors within this income range. | 0.12 |
| people_fraction_income_50k_75k | float | Estimated fraction of visitors within this income range. | 0.232 |
| people_fraction_income_75k_100k | float | Estimated fraction of visitors within this income range. | 0.118 |
| people_fraction_income_100k_125k | float | Estimated fraction of visitors within this income range. | 0.118 |
| people_fraction_income_125k_and_above | float | Estimated fraction of visitors within this income range. | 0.282 |
| people_fraction_race_amerindian | float | Estimated fraction of visitors with this race. | 0.063 |
| people_fraction_race_asian | float | Estimated fraction of visitors with this race. | 0.038 |
| people_fraction_race_black | float | Estimated fraction of visitors with this race. | 0.025 |
| people_fraction_race_white | float | Estimated fraction of visitors with this race. | 0.777 |
| people_fraction_race_other | float | Estimated fraction of visitors with this race. | 0.017 |
| people_fraction_race_two_or_more | float | Estimated fraction of visitors with this race. | 0.072 |
Locations Schema: Predifned POIs locations
In addition to the schemas above describing the metrics, we provide optional schemas supporting contextual information of 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 |
| stock_symbol | STRING | The stock ticker (if the corporation is traded publicly) | F |
| stock_exchange | STRING | The stock exchange on which this corporation is listed (if the corporation is traded publicly). | NYSE |
| iso_country_codes_open | STRING | A list of all 2 letter ISO 3166-1 alpha-2 country codes for each country this brand has at least 1 open POI (closed_on is null). | ["US", "GB"] |
| iso_country_codes_closed | STRING | A list of all 2 letter ISO 3166-1 alpha-2 country codes for each country this brand has at least 1 closed POI (closed_on is not null). | ["US", "CA"] |
| 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 |
Visitation on Neighbourhoods
Foot-traffic Weekly Dataset - Neighbourhoods
Foot-traffic describes the median estimated daily visitors to the location aggregated on a weekly basis.
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | 560050007011 |
| 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. | 2772 |
| visits_p50 | int | Estimated median of unique people per day at the location during the observation period. Includes all people even residents and workers. | 449 |
| non_resident_non_worker_visits_sum | int | Estimated sum of daily visitors to the location during the observation period. Excludes residents and workers of the location. | 5591 |
| non_resident_non_worker_visits_p50 | int | Estimated median of daily visitors to the location during the observation period. Excludes residents and workers of the location. | 324 |
| resident_visits_sum | int | Estimated sum of residents (Home at given location) to the location during the observation period. | 3003 |
| resident_visits_p50 | int | Estimated median of daily residents (Home at given location) to the location during the observation period. | 388 |
| worker_visits_sum | int | Estimated sum of workers (Work at given location) to the location during the observation period. | 1432 |
| worker_visits_p50 | int | Estimated median of daily workers (Work at given location) to the location during the observation period. | 319 |
Foot-traffic Monthly Dataset - Neighbourhoods
Foot-traffic describes the median estimated daily visitors to the location aggregated on a monthly basis.
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | 560050007011 |
| observation_start_date | string (yyyy-mm-dd) | The start date for the period this observation took place. | 2024-01-01 |
| observation_end_date | string (yyyy-mm-dd) | The end date for the period this observation took place. | 2024-01-31 |
| visits_sum | int | Estimated sum of unique people per day at the location during the observation period. Includes all people even residents and workers. | 2772 |
| visits_p50 | int | Estimated median of unique people per day at the location during the observation period. Includes all people even residents and workers. | 449 |
| non_resident_non_worker_visits_sum | int | Estimated sum of daily visitors to the location during the observation period. Excludes residents and workers of the location. | 5591 |
| non_resident_non_worker_visits_p50 | int | Estimated median of daily visitors to the location during the observation period. Excludes residents and workers of the location. | 324 |
| resident_visits_sum | int | Estimated sum of residents (Home at given location) to the location during the observation period. | 3003 |
| resident_visits_p50 | int | Estimated median of daily residents (Home at given location) to the location during the observation period. | 388 |
| worker_visits_sum | int | Estimated sum of workers (Work at given location) to the location during the observation period. | 1432 |
| worker_visits_p50 | int | Estimated median of daily workers (Work at given location) to the location during the observation period. | 319 |
Trade Area by CBG Quarterly Dataset - Neighbourhoods
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. | 120479601032 |
| trade_area_location_id | string | ID of US Census block groups (CBG) | 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 Quarterly Dataset - Neighbourhoods
| Field name | Type | Description | Example |
|---|---|---|---|
| location_id | string | The geographical identification of a value in the data set. | 120479601032 |
| observation_start_date | string (yyyy-mm-dd) | The start date for the period this observation took place. | 2019-04-01 |
| observation_end_date | string (yyyy-mm-dd) | The end date for the period this observation took place. | 2019-06-30 |
| people_fraction_age_18_29 | float | Estimated fraction of visitors within this age group. | 0.185 |
| people_fraction_age_30_39 | float | Estimated fraction of visitors within this age group. | 0.179 |
| people_fraction_age_40_49 | float | Estimated fraction of visitors within this age group. | 0.154 |
| people_fraction_age_50_59 | float | Estimated fraction of visitors within this age group. | 0.176 |
| people_fraction_age_60_69 | float | Estimated fraction of visitors within this age group. | 0.166 |
| people_fraction_age_70_79 | float | Estimated fraction of visitors within this age group. | 0.094 |
| people_fraction_age_80_and_above | float | Estimated fraction of visitors within this age group. | 0.046 |
| people_fraction_education_high_school | float | Estimated fraction of visitors with this education level. | 0.213 |
| people_fraction_education_college_without_degree | float | Estimated fraction of visitors with this education level. | 0.228 |
| people_fraction_education_associate | float | Estimated fraction of visitors with this education level. | 0.087 |
| people_fraction_education_bachelor | float | Estimated fraction of visitors with this education level. | 0.194 |
| people_fraction_education_master_and_above | float | Estimated fraction of visitors with this education level. | 0.082 |
| people_fraction_gender_female | float | Estimated fraction of visitors with this gender. | 0.494 |
| people_fraction_gender_male | float | Estimated fraction of visitors with this gender. | 0.506 |
| people_fraction_income_25k_and_less | float | Estimated fraction of visitors within this income range. | 0.128 |
| people_fraction_income_25k_50k | float | Estimated fraction of visitors within this income range. | 0.12 |
| people_fraction_income_50k_75k | float | Estimated fraction of visitors within this income range. | 0.232 |
| people_fraction_income_75k_100k | float | Estimated fraction of visitors within this income range. | 0.118 |
| people_fraction_income_100k_125k | float | Estimated fraction of visitors within this income range. | 0.118 |
| people_fraction_income_125k_and_above | float | Estimated fraction of visitors within this income range. | 0.282 |
| people_fraction_race_amerindian | float | Estimated fraction of visitors with this race. | 0.063 |
| people_fraction_race_asian | float | Estimated fraction of visitors with this race. | 0.038 |
| people_fraction_race_black | float | Estimated fraction of visitors with this race. | 0.025 |
| people_fraction_race_white | float | Estimated fraction of visitors with this race. | 0.777 |
| people_fraction_race_other | float | Estimated fraction of visitors with this race. | 0.017 |
| people_fraction_race_two_or_more | float | Estimated fraction of visitors with this race. | 0.072 |
Location schema: CBG locations
In addition to the schemas above describing the metrics, we provide optional schemas supporting contextual information of locations.
| Field name | Type | Description | Example |
|---|---|---|---|
| area | int | Size of area in square meters (m2, sqm) | 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) | 41740 |
| us_cbsa | string | Name of US Core-Based Statistical Area | San Diego-Chula Vista-Carlsbad, CA Metro Area |
Custom Locations context
Since custom locations are provided by the user, we do not have additional context to provide.