SafeGraph Places includes four primary datasets:
- Core Places: Base information about a point of interest (POI) such as location name, address and brand association for top ~3,000 national brands. Available for ~5MM POI.
- Geometry: Building geometry information for commercial POIs that includes the building footprint as a polygon and spatial hierarchy metadata defining whether the polygon is contained within another POI. Available for ~5MM POI.
- Patterns: Place traffic and demographic aggregations that answer: how often people visit, where they came from, where else they go, and more. Available for ~3.25MM POI.
- IP-to-Place: WiFi IP address ranges for each POI overtime. Available for ~1.8MM POI.
All SafeGraph Places datasets utilize safegraph_place_id as the primary key, are formatted as delimited CSVs, and can be purchased independently.
SafeGraph updates the Places dataset every month with the past month's openings and closings and maintains a persistent SafeGraph Place ID (safegraph_place_id) across releases. Please refer to Places Data Manual for detailed field definitions and Places Summary Statistics for data coverage information.
Core Places
Base information about a place such as location name, address, lat/long, and brand. Available for ~5MM POI.
| Column Name | Description | Type | Example |
|---|---|---|---|
safegraph_place_id |
Unique and consistent ID that is tied to this POI. | String | sg:64d0ee4695af4ab4906fe82997ead9ff |
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. |
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 |
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 | salinas |
state |
The state (as postal code abbreviation) in which this point of interest is located. | String | ca |
zip_code |
Postal 5-digit ZIP code. | Integer | 93907 |
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. | 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": [] } |
Brand Info
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 with ~3,000 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 consistent 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 |
Geometry
Building geometry information for commercial POIs that includes latitude/longitude and the building footprint as a polygon and spatial hierarchy metadata defining whether the polygon is contained within another POI. Available for ~5MM POI.
| Column Name | Description | Type | Example |
|---|---|---|---|
safegraph_place_id |
Unique and consistent ID that is tied to this POI. | String | sg:64d0ee4695af4ab4906fe82997ead9ff |
latitude |
Latitude coordinate of the place of interest. | Float | 36.714767 |
longitude |
Longitude coordinate of the place of interest. | Float | -121.662912 |
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 POI itself. However, if we do not have a POI's co-tenant of a building in our dataset it is possible that a POI will have the OWNED_POLYGON value but in actuality, the polygon includes another tenant. 2) SHARED_POLYGON: indicates that at least two POI shared the same polygon. This could be, for example, because (a) the polygon is attached to this POI as well as a parent / enclosing structure (e.g. the mall that contains this POI), or (b) “peer” POI are given the single polygon (e.g. POI on different floors). |
String | OWNED_POLYGON |
includes_parking_lot |
Whether or not the polygon includes the parking lot or just the building. | Boolean | false |
Patterns
Places Patterns is a dataset of visitor and demographic aggregations available for ~3.25MM POI that answers the following questions and more:
- How many visits from our panel did this place see?
- How many unique visitors from our panel went to this place?
- Where do these visitors live and work?
- Which other brands did these visitors go to in the same day or month?
- What times of day do people visit this place?
- How far do visitors travel to this place from home?
- How long do visitors stay at this place?.
| Column Name | Description | Type | Example |
|---|---|---|---|
safegraph_place_id |
Unique and consistent ID that is tied to this POI. | String | sg:64d0ee4695af4ab4906fe82997ead9ff |
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 | salinas |
state |
The state (as postal code abbreviation) in which this point of interest is located. | String | ca |
zip_code |
Postal 5-digit ZIP code. | Integer | 93907 |
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 as a timestamp in UTC in seconds since January 1, 1970. | Long | 1535760000 |
date_range_end |
End time for measurement period as a timestamp in UTC in seconds since January 1, 1970. | Long | 1538351999 |
raw_visit_counts |
Number of visits to this POI during the date range. | Integer | 1542 |
raw_visitor_counts |
Number of unique visitors to this POI during the date range. | Integer | 1221 |
visits_by_day |
The number of visits to the POI each day (local time) over the covered time period. | 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] |
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 5 visitors are shown. | JSON {String: Integer} | {"360610112021": 33898, "460610112021": 12323, "560610112021": 8423, "660610112021": 7342, "660610112021": 51} |
visitor_work_cbgs |
A mapping of census block groups to the number of visitors to the POI whose work place is in that census block group. Only CBGs with at least 5 visitors are shown. | JSON {String: Integer} | {"360610112021": 33898,"460610112021": 12323,"560610112021": 8423,"660610112021": 7342, "660610112021": 51} |
visitor_country_of_origin |
A mapping of country coce to the number of visitors to the POI whose home is in that country. Only countries with at least 5 visitors are shown. | 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. | Integer | 1211 |
median_dwell |
Median minimum dwell time in minutes. | Double | 5 |
bucketed_dwell_times |
Key is range of minutes and value is number of visits that were within that duration. | 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). |
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). |
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. | 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. | 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. | JSON {String: Integer} | {"android": 6, "ios": 8} |
Along with the Patterns file, we also deliver Panel Overview Data (see 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
| 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 |
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
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 visits observed in the specified state | Int | 8900 |
num_unique_visitors |
Number of unique visitors observed with at least 1 visit in the specified state | Integer | 966 |
Number of Unique Visitors to Each Brand (Enterprise Version Only)
| Column Name | Description | Type | Example |
|---|---|---|---|
brand |
Name of brand | String | 16 Handles |
unique_visitors |
Number of unique visitors observed with at least 1 visit to the specified brand | Integer | 966 |
year |
Calendar Year | Integer | 2018 |
month |
Calendar month starting from 1 as January | Integer | 1 |
IP-to-Place
IP-to-Place includes WiFi address ranges for SafeGraph Places overtime. Available for ~1.8MM POIs.
IP-to-Place data is delivered with all Core Places fields.
| Column Name | Description | Type | Example |
|---|---|---|---|
safegraph_place_id |
Unique and consistent ID that is tied to this POI. | String | sg:64d0ee4695af4ab4906fe82997ead9ff |
start_ip |
The start of the IP range. | String | 4.15.103.185 |
end_ip |
The end of the IP range. | String | 4.15.103.190 |
first_ping_time |
The first time at which the IP range was seen in local time in seconds since epoch of January 1, 1970. | Long | 1528675200 |
last_ping_time |
The last time at which the IP range was seen in local time in seconds since epoch of January 1, 1970. | Long | 1529280005 |