SafeGraph Places includes three primary datasets:
- Core Places: Base information such as location name, address, category, and brand association for points of interest (POIs) where people spend time or money. Available for ~7MM POI including permanently closed POIs.
- Geometry: POI footprints with spatial hierarchy metadata depicting when child polygons are contained by parents or when two tenants share the same polygon. Available for ~6.5MM POI (Geometry metadata not provided for closed POIs).
- Patterns: Place traffic and demographic aggregations that answer: how often people visit, how long they stay, where they came from, where else they go, and more. Available for ~4.4MM POI.
SafeGraph updates the Places dataset every month with the past month's openings and closings and maintains a persistent placekey across releases.
Please refer to the Places Data Manual for detailed field definitions and Places Summary Statistics for data coverage information.
All SafeGraph Places datasets utilize placekey as the primary key, are formatted as delimited CSVs, and can be purchased independently or together. Please reference the SafeGraph Attribute Matrix for a breakdown of which columns are available per product, and reference the Column Orderings section in the Places Manual for specific column orderings per product combination. Otherwise, stand-alone purchases will follow the column ordering listed in the schemas below:
Core Places
[core_poi.csv]
Base information about a place such as location name, address, lat/long, category, brand and more. Available for ~7MM POI including permanently closed POIs.
* only pertinent to files including closed POIs
| Column Name | Description | Type | Example |
|---|---|---|---|
placekey |
Unique and persistent ID tied to this POI. See the Places Manual for details on placekey design. | String | [email protected] |
safegraph_place_id |
Unique and persistent ID tied to this POI (to be retired in favor of placekey). |
String | sg:64d0ee4695af4ab4906fe82997ead9ff |
parent_placekey |
If place is a tenant / sub-store inside a larger place (e.g. mall, airport, stadium), this lists the placekey of the parent place, otherwise null. See more on parent-child relationships in the Places Manual. |
String | [email protected] |
parent_safegraph_place_id |
If place is encompassed a larger place (e.g. mall, airport, stadium), this lists the safegraph_place_id of the parent place; otherwise null (to be retired in favor of parent_placekey). See more on parent-child relationships in the Places Manual. |
String | sg:3134d87532ae4e32acf4007eb03eabb5 |
location_name |
The name of the place of interest. | String | Salinas Valley Ford Lincoln |
safegraph_brand_ids |
Unique and consistent ID that represents this specific brand. | List | SG_BRAND_80ca06abfa1a5104af9a770f485dad07, SG_BRAND_aa45997477591e27601c436bcb228d6f |
brands |
If this POI is an instance of a larger brand that we have explicitly identified, this column will contain that brand name. This is an easy way to, for example, unambiguously select all Target stores in the USA. A POI may have multiple brands, as in a new car dealership that sells ford and lincoln cars. |
List | Ford, Lincoln |
top_category |
The label associated with the first 4 digits of the POI’s NAICS category. | String | Automobile Dealers |
sub_category |
The label associated with all 6 digits of the POI’s NAICS category. | String | New Car Dealers |
naics_code |
6-digit NAICS code describing the business. | Integer | 441110 |
latitude |
Latitude coordinate of the place of interest. | Float | 36.714767 |
longitude |
Longitude coordinate of the place of interest. | Float | -121.662912 |
street_address |
Street address of the place of interest. | String | 1100 Auto Center Circle |
city |
The city in which this point of interest is located. | String | Irvine |
region |
When iso_country_code == US, then this is the USA state or territory. When iso_country_code == CA, then this is the Canadian Province or territory. |
String | CA |
postal_code |
When iso_country_code == US, then this is the USA 5 digit zip code. When iso_country_code == CA, then this is the Canadian postal code in the form of a 3 digit Forward Sortation Area (FSA), a space, and the 3 digit Local Delivery Unit (LDU). |
String | 92602 |
iso_country_code |
The 2 letter ISO 3166-1 alpha-2 country code. Expected values are US and CA. |
String | US |
phone_number |
The phone number of this POI | String | +14151234567 |
open_hours |
A JSON string with days as keys and opening & closing times (in the POI's local time) as values. See more info in Places Manual | String | { "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": [] } |
category_tags |
For POI with naics_code starting 722, we provide an array of descriptive tags indicating higher-resolution category information. See also: Places Manual |
List | [Mexican Food,Casual Dining,Lunch,Dinner] |
*opened_on |
The outside year and month this POI opened in yyyy-mm format. If null, then this POI either opened before our earliest metadata on this POI (see tracking_opened_since), or we do not have enough metadata to determine an open date. See more info in the Places Manual |
String | 2019-10 |
*closed_on |
The outside year and month this POI closed in yyyy-mm format. If null, then this POI is open. See the Places Manual for details on interpreting closed_on = "2020-01" |
String | 2020-03 |
*tracking_opened_since |
Indicates the year and month we started tracking "opened_on" for this POI. See more info in the Places Manual | String | 2019-07 |
*tracking_closed_since |
Indicates the year and month we started tracking "closed_on" for this POI. See more info in the Places Manual | String | 2019-07 |
Brand Info
[brand_info.csv]
A SafeGraph brand is defined as a logo or branded store which has multiple locations all under the same logo or store banner. For a deep dive on how we think about brands, see our November 2018 Release Notes.
The brand_info file is a separate csv that is complimentary with a core places purchase. It contains ~5,600 records where each record is a distinct brand, defined by the safegraph_brand_id. A brand can be associated with many POI. For example, McDonald’s is represented as a single record in brand_info and there are approximately 14K POIs associated with the McDonald’s brand. Brands can be children or parents of other brands. For example InterContinental Hotels Group (SG_BRAND_70b1db807a0fc63d) is the parent company of multiple subsidiary brands, including InterContintinental Hotels & Resorts (SG_BRAND_d967f05785d000fd) (see also Release Notes Jan 2019)
| Column Name | Description | Type | Example |
|---|---|---|---|
safegraph_brand_id |
Unique and persistent ID that represents this specific brand. | String | SG_BRAND_80ca06abfa1a5104af9a770f485dad07 |
brand_name |
This is the brand_name corresponding to the safegraph_brand_id. |
String | Ford Motor Company |
parent_safegraph_brand_id |
There are 2 possible values: 1) If this brand has a parent, this will list the ID of the parent brand. 2) If this brand has no parent, this will be null. |
String | SG_BRAND_8310c2e3461b8b5a |
naics_code |
6-digit NAICS code describing the business. | Integer | 441110 |
top_category |
The label associated with the first 4 digits of the POI’s NAICS category. | String | Automobile Dealers |
subcategory |
The label associated with all 6 digits of the POI’s NAICS category. | String | New Car Dealers |
stock_symbol |
The stock ticker (if the corporation is traded publicly) | String | F |
stock_exchange |
The stock exchange on which this corporation is listed (if the corporation is traded publicly). | String | NYSE |
Geometry
[geometry.csv or geometry.zip for SHP files]
POI footprints and spatial hierarchy metadata. Available for ~6.5MM POI (Geometry metadata not provided for closed POIs).
| Column Name | Description | Type | Example |
|---|---|---|---|
placekey |
Unique and persistent ID tied to this POI. See the Places Manual for details on placekey design. | String | [email protected] |
safegraph_place_id |
Unique and persistent ID tied to this POI (to be retired in favor of placekey). |
String | sg:64d0ee4695af4ab4906fe82997ead9ff |
parent_placekey |
If place is a tenant / sub-store inside a larger place (e.g. mall, airport, stadium), this lists the placekey of the parent place, otherwise null. See more on parent-child relationships in the Places Manual. |
String | [email protected] |
parent_safegraph_place_id |
If place is a tenant / sub-store inside a larger place (e.g. mall, airport, stadium), this lists the safegraph_place_id of the parent place, otherwise null (to be retired in favor of parent_placekey). See more on parent-child relationships in the Places Manual. |
String | sg:3134d87532ae4e32acf4007eb03eabb5 |
location_name |
The name of the place of interest. | String | Salinas Valley Ford Lincoln |
brands |
If this POI is an instance of a larger brand that we have explicitly identified, this column will contain that brand name. This is an easy way to, for example, unambiguously select all Target stores in the USA. A POI may have multiple brands, as in a new car dealership that sells ford and lincoln cars. |
List | Ford, Lincoln |
latitude |
Latitude coordinate of the place of interest. | Float | 36.714767 |
longitude |
Longitude coordinate of the place of interest. | Float | -121.662912 |
street_address |
Street address of the place of interest. | String | 1100 Auto Center Circle |
city |
The city in which this point of interest is located. | String | Irvine |
region |
When iso_country_code == US, then this is the USA state or territory. When iso_country_code == CA, then this is the Canadian Province or territory. |
String | CA |
postal_code |
When iso_country_code == US, then this is the USA 5 digit zip code. When iso_country_code == CA, then this is the Canadian postal code in the form of a 3 digit Forward Sortation Area (FSA), a space, and the 3 digit Local Delivery Unit (LDU). |
String | 92602 |
iso_country_code |
The 2 letter ISO 3166-1 alpha-2 country code. Expected values are US and CA. |
String | US |
polygon_wkt |
The shape of the place of interest, formatted as Well-Known Text (WKT). | String | Polygon ((-121.66331045329571 36.715207502522354, …, -121.66331045329571 36.715207502522354)) |
polygon_class |
There are 2 possible values: 1) OWNED_POLYGON: indicates that the polygon describes the shape and size of the POI itself, and only one POI maps to this distinct polygon excluding that POI's children. However, if we do not have a POI's co-tenant in our dataset, it is possible that a POI will have the OWNED_POLYGON value but, in reality, the polygon includes another tenant. 2) SHARED_POLYGON: indicates that at least two POIs share the same polygon, and the POIs sharing the polygon are not "parents" nor "children" of each other. See the Polygon Class section of the Places Manual for more on how we think about polygon classification. |
String | OWNED_POLYGON |
includes_parking_lot |
Whether or not the polygon includes the parking lot or just the building. | Boolean | false |
is_synthetic |
If true then this is not a precise POI footprint polygon, but instead is an inferred polygon from an accurate centroid, category-based radius, and heuristics like avoiding overlap with roads. See the Places Manual for more details. |
Boolean | false |
building_height |
When the polygon represents a building, this is the height above ground of the building in meters. | String | 25 |
enclosed |
If true, then this POI is completely enclosed indoors by its parent and is only accessible by entering the parent structure. Visits are not assigned to POIs when enclosed is true and are instead assigned to the parent POI. | Boolean | false |
Patterns
[patterns.csv]
Patterns is a dataset of visitor and demographic aggregations available for ~4.4MM POI.
| Column Name | Description | Type | Example |
|---|---|---|---|
placekey |
Unique and persistent ID tied to this POI. See the Places Manual for details on placekey design. | String | [email protected] |
safegraph_place_id |
Unique and persistent ID tied to this POI (to be retired in favor of placekey). |
String | sg:64d0ee4695af4ab4906fe82997ead9ff |
parent_placekey |
If place is a tenant / sub-store inside a larger place (e.g. mall, airport, stadium), this lists the placekey of the parent place, otherwise null. See more on parent-child relationships in the Places Manual. |
String | [email protected] |
parent_safegraph_place_id |
If place is encompassed a larger place (e.g. mall, airport, stadium), this lists the safegraph_place_id of the parent place; otherwise null (to be retired in favor of parent_placekey). See more on parent-child relationships in the Places Manual. |
String | sg:3134d87532ae4e32acf4007eb03eabb5 |
location_name |
The name of the place of interest. | String | Salinas Valley Ford Lincoln |
street_address |
Street address of the place of interest. | String | 1100 Auto Center Circle |
city |
The city in which this point of interest is located. | String | Irvine |
region |
When iso_country_code == US, then this is the USA state or territory. When iso_country_code == CA, then this is the Canadian Province or territory. |
String | CA |
postal_code |
When iso_country_code == US, then this is the USA 5 digit zip code. When iso_country_code == CA, then this is the Canadian postal code in the form of a 3 digit Forward Sortation Area (FSA), a space, and the 3 digit Local Delivery Unit (LDU). |
String | 92602 |
safegraph_brand_ids |
Unique and consistent ID that represents this specific brand. | List | SG_BRAND_80ca06abfa1a5104af9a770f485dad07, SG_BRAND_aa45997477591e27601c436bcb228d6f |
brands |
If this POI is an instance of a larger brand that we have explicitly identified, this column will contain that brand name. This is an easy way to, for example, unambiguously select all Target stores in the USA. A POI may have multiple brands, as in a new car dealership that sells ford and lincoln cars. |
List | ford, lincoln |
date_range_start |
Start time for measurement period in ISO 8601 format of YYYY-MM-DDTHH:mm:SS±hh:mm (local time with offset from GMT). | String | 2020-03-01T00:00:00-06:00 |
date_range_end |
End time for measurement period in ISO 8601 format of YYYY-MM-DDTHH:mm:SS±hh:mm (local time with offset from GMT). The end time will be the last day of the month at 12 a.m. local time. | String | 2020-03-31T00:00:00-06:00 |
raw_visit_counts |
Number of visits in our panel to this POI during the date range. | Integer | 1542 |
raw_visitor_counts |
Number of unique visitors from our panel to this POI during the date range. See also, Places Manual. | Integer | 1221 |
visits_by_day |
The number of visits to the POI each day (local time) over the covered time period. See also, Places Manual | JSON [Integer] | [33, 22, 33, 22, 33, 22, 22, 21, 23, 33, 22, 11, 44, 22, 22, 44, 11, 33, 44, 44, 44, 33, 34, 44, 22, 33, 44, 44, 34, 43, 43] |
poi_cbg |
The census block group the POI is located within. | String | 560610112022 |
visitor_home_cbgs |
A mapping of census block groups to the number of visitors to the POI whose home is in that census block group. Only cbgs with at least 2 devices are shown and cbgs with less than 5 devices are reported as 4. See more on privacy here: Places Manual. | JSON {String: Integer} | {"360610112021": 603, "460610112021": 243, "560610112021": 106, "660610112021": 87, "660610112021": 51} |
visitor_daytime_cbgs |
A mapping of census block groups to the number of visitors to the POI whose primary daytime location between 9 am - 5 pm is in that census block group. Only cbgs with at least 2 devices are shown and cbgs with less than 5 devices are reported as 4. See more on privacy here: Places Manual. | JSON {String: Integer} | {"360610112030": 9872, "880610112021": 8441, "569610112020": 5671, "160610112041": 2296, "980610112021": 1985} |
visitor_country_of_origin |
A mapping of country code to the number of visitors to the POI whose home is in that country. Only countries with at least 2 devices are shown and countries with fewer than 5 devices are reported as 4. See more on privacy here: Places Manual | JSON {String: Integer} | {"US": 98,"CA": 12} |
distance_from_home |
Median distance from home travelled by visitors (of visitors whose home we have identified) in meters. See also, Places Manual | Integer | 1211 |
median_dwell |
Median minimum dwell time in minutes. See also, Places Manual | Double | 5 |
bucketed_dwell_times |
Key is range of minutes and value is number of visits that were within that duration. See also, Places Manual | JSON {String: Integer} | { "<5": 40, "5-20": 22, "21-60": 45, "61-240": 3,">240": 5} |
related_same_day_brand |
Other brands that the visitors to this POI visited on the same day as the visit to this POI where customer overlap differs by at least 5% from the SafeGraph national average. The mapping has the brand as the key. The value shown for each brand is a percentage representing the median of the following calculation for each day in the month: (same-day visitors to both the brand and the POI / total daily visitors to the POI) - (daily visitors to the brand / all visitors in SafeGraph panel). See also, Places Manual |
JSON {String: Integer} | {"mcdonalds": 7,"amc": 5,"target": 3} |
related_same_month_brand |
Other brands that the visitors to this POI visited in the same month as the visit to this POI where customer overlap differs by at least 5% from the SafeGraph national average. The value shown for each brand is a percentage representing: (visitors to both the brand and the POI / total visitors to the POI) - (visitors to the brand / all visitors in SafeGraph panel). See also, Places Manual |
JSON {String: Integer} | {"mcdonalds": 7,"amc": 5,"target": 3} |
popularity_by_hour |
A mapping of hour of day to the number of visits in each hour over the course of the date range in local time. First element in the array corresponds to the hour of midnight to 1 am. See also, Places Manual | JSON [Integer] | [ 0, 0, 0, 0, 0, 0, 0, 222, 546, 444, 333, 232, 432, 564, 456, 345, 678, 434, 545, 222, 0, 0, 0, 0 ] |
popularity_by_day |
A mapping of day of week to the number of visits on each day (local time) in the course of the date range. See also, Places Manual | JSON {String: Integer} | {"Monday": 3300,"Tuesday": 1200,"Wednesday": 898,"Thursday": 7002,"Friday": 5001,"Saturday": 5987,"Sunday": 0} |
device_type |
The number of visitors to the POI that are using android vs. ios. Only device_type with at least 2 devices are shown and any category with less than 5 devices are reported as 4. See more on privacy here: Places Manual | JSON {String: Integer} | {"android": 6, "ios": 8} |
†carrier_name |
A mapping of wireless carrier names to the number of visitors to the POI whose device uses that wireless carrier. Only carrier_names with at least 2 devices are shown, and carrier_names with less than 5 devices are reported as 4. See more on privacy here: Places Manual | JSON {String: Integer} | {"Verizon": 342, "T-Mobile": 288, "AT&T": 265} |
† carrier_name is a premium column. Please Contact Sales for more details.
Along with the Patterns file, we also deliver Panel Overview Data (see tables below) to help you better understand the context of the data appearing in Places Patterns.
Panel Overview Data
Home Location Distributions by State/Census Block Group
[home_panel_summary.csv]
| Column Name | Description | Type | Example |
|---|---|---|---|
year |
Calendar Year | Integer | 2018 |
month |
Calendar month starting from 1 as January | Integer | 1 |
state |
Lowercase abbreviation of U.S. state or territory | String | ca |
census_block_group |
FIPS code for this Census block group | String | 530330080012 |
number_devices_residing |
Number of distinct devices observed with a primary nighttime location in the specified census block group. | Integer | 54481 |
Number of Visits/Visitors by State
[visit_panel_summary.csv]
Note: Includes one row with ALL_STATES to provide total visitors seen in the month (might be less than sum of visitors by state due to same visitors having visits in multiple states).
| Column Name | Description | Type | Example |
|---|---|---|---|
year |
Calendar Year | Integer | 2018 |
month |
Calendar month starting from 1 as January | Integer | 1 |
state |
Lowercase abbreviation of U.S. state or territory | String | ca |
num_visits |
Number of point-of-interest visits observed in the specified state | Int | 8900 |
num_unique_visitors |
Number of unique visitors observed with at least 1 point-of-interest visit in the specified state | Integer | 966 |
Normalization Stats
[normalization_stats.csv]
| Column Name | Description | Type | Example |
|---|---|---|---|
year |
Calendar Year | Integer | 2018 |
month |
Calendar month starting from 1 as January | Integer | 1 |
day |
Calendar day | Integer | 1 |
region |
When iso_country_code == US, then this is the USA state or territory. When iso_country_code == CA, then this is the Canadian Province or territory. | String | CA |
total_visits |
All visits we saw on the given day in local time (includes visits to POI and visits to homes) | Integer | 200 |
total_devices_seen |
Total devices in our panel which we saw on the given day with any visit in local time (POI or home visit) | Integer | 50 |
total_home_visits |
Visits we saw on the given day in local time to the device's home geohash-7 | Integer | 120 |
total_home_visitors |
Total devices we saw on the given day with at least 1 visit to the device's home geohash-7 | Integer | 35 |
Updated about a month ago