The SafeGraph Developer Hub

Welcome to the SafeGraph developer hub. You'll find comprehensive guides and documentation to help you start working with SafeGraph as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Weekly Patterns v1 [deprecated]

As of 2020-05-20 Weekly Patterns v1 is no longer supported. You are strongly encouraged to switch to Weekly Patterns v2

Due to the COVID-19 Pandemic, commercial patterns have been severely disrupted. In order to provide timely insights into this situation, SafeGraph is offering a temporary Weekly Patterns product.

Weekly Patterns is very similar to our normal Patterns product with a few differences:

1) Each delivery of Weekly Patterns will cover one week starting Sunday and ending Saturday. The data will be available three days later on Tuesday of each week.

2) We have Weekly Patterns starting from March 1, 2020. For historical beyond that, the regular Patterns file should be used.

3) In Weekly Patterns, we added a naics_code column to make grouping by category easier.

4) In Weekly Patterns, we added a visits_by_each_hour column to enable you to get a more detailed view of the week.

5) Weekly Patterns does not include visitor_work_cbgs (data is too sparse), popularity_by_hour (covered by visits_by_each_hour) and popularity_by_day (covered by visits_by_each_hour).

Schema

[main-file]

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 Irvine
region The state or territory. String CA
postal_code 5 digit zip code String 92602
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
naics_code 6-digit NAICS code describing the business. Integer 441110
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). The start time will be 12 a.m. Sunday in local time. 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 following Sunday at 12 a.m. local time. String 2020-03-08T00: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. 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]
visits_by_each_hour The number of visits to the POI for each of the 168 hours of the week. 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. See Privacy Section below. JSON {String: Integer} {"360610112021": 603, "460610112021": 243, "560610112021": 106, "660610112021": 87, "660610112021": 51}
visitor_country_of_origin A mapping of country code to the number of visitors to the POI whose home is in that country. See Privacy Section below. 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). This column will only contain values if there are at least 5 visitors to the POI. JSON {String: Integer} {"mcdonalds": 7,"amc": 5,"target": 3}
related_same_week_brand Other brands that the visitors to this POI visited in the same week 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). This column will only contain values if there are at least 5 visitors to the POI. JSON {String: Integer} {"mcdonalds": 7,"amc": 5,"target": 3}
device_type The number of visitors to the POI that are using android vs. ios. See Privacy Section below. JSON {String: Integer} {"android": 6, "ios": 8}
iso_country_code The 2 letter ISO 3166-1 alpha-2 country code. String US

Along with the Weekly Patterns file, we deliver a breakdown of the home origin of the devices each week to help you better understand the context of the data appearing in Weekly Patterns.

Home Location Distributions by State/Census Block Group

[home_summary_file]

Column Name Description Type Example
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). The start time will be 12 a.m. Sunday in local time. 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 following Sunday at 12 a.m. local time. String 2020-03-08T00:00:00-06:00
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

* Normalization Stats [NEW as of 04-05!!]

[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
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

Privacy

For all releases prior to 04-05, we excluded home_cbgs and country_of_origin if there were fewer than 5 visitors from a census block group or country of origin, as applicable.

Beginning with the 04-05 release, we apply differential privacy to the counts in home_cbgs, country_of_origin and device_types. We do not include a census block group or country of origin unless there are at least 2 visitors from that census block group or country of origin or with that device type as applicable. If there are between 2 and 4 visitors we show this count as 4.

Version Map

To map our Weekly Patterns to the underlying Core Places file used to generate it, please see the table below:

Weekly Patterns Release
Core Places Version

v1/2020-03-01

March-2020

v1/2020-03-08

March-2020

v1/2020-03-15

March-2020

v1/2020-03-22

March-2020

v1/2020-03-29

April-2020

v1/2020-04-05-corrected

April-2020

v1/2020-04-12

April-2020

v1/2020-04-19

April-2020

v1/2020-04-26

May-2020

Updated 4 months ago


Weekly Patterns v1 [deprecated]


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.