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    

Neighborhood Patterns

What is it?

SafeGraph Neighborhood Patterns contains footfall data aggregated by census block group.

Use the data to answer:

  • Which day of the week is a CBG busiest?
  • When during the day is a CBG busy?
  • Where do the devices that stop in a CBG during breakfast, lunch or dinner travel from?
  • How do the weekday demographics of a CBG compare to the weekend demographics?

This data is ideal for site-selection use cases and other use cases where you need to understand how busy an area is, when it is busy and the demographics of the visitors. For more information see our Neighborhood Patterns announcement.

Download a free sample of Neighborhood Patterns here.

How was it created?

The data was generated by:

  • creating clusters of pings from a panel of anonymous mobile devices using DBSCAN
  • filtering out any cluster that had a duration of less than 1 minute
  • counting each resulting cluster as a "stop"
  • aggregating the stops by census block group.

The data is released monthly (by the 7th) with each monthly release reflecting what occurred during the prior calendar month.

Privacy Protections

To preserve privacy, we apply differential privacy techniques to the following columns: device_home_areas
workday_device_home_areas
weekday_device_home_areas
weekend_device_home_areas
breakfast_device_home_areas
lunch_device_home_areas
afternoon_tea_device_home_areas
dinner_device_home_areas
nightlife_device_home_areas
device_daytime_areas
device_type

We have added Laplacian noise to the values in these columns. After adding noise, only attributes (e.g., a census block group) with at least two devices are included in the data.
For these columns, we do not report data unless at least 2 visitors are observed from that group. If there are between 2 and 4 visitors this is reported as 4.

Schema

Column Name Description Type Example
area The designation of the area being described. String 131000000000
area_type The type of area specified in the area column. String Census Block Group
origin_area_type The type of area used in the device_home_areas and device_daytime_areas columns. String Census Block Group
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-04-01T00:00:00-06:00
day_counts A count of the number of each day of the week that occurred in the date range in local time. JSON {String:Int} {"Monday": 4, "Tuesday": 5, "Wednesday": 4, "Thursday": 4, "Friday": 4, "Saturday": 4, "Sunday": 4 }
raw_stop_counts Number of stops by devices in our panel to this area during the date range. A stop must have a minimum duration of 1 minute to be included. The count includes stops by devices whose home area is the same as this area. Integer 428840
raw_device_counts Number of unique devices in our panel that stopped in this area during the date range. This includes devices whose home area is the same as this area. Integer 109161
stops_by_day The number of stops in this area 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]
stops_by_each_hour The number of stops in this area each hour (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....]
device_home_areas A mapping of home origin area to the number of visitors to this area. Home area is the common nighttime location for the device where nighttime is 6 pm - 7 am. The count of visitors that originate from the area itself is included and the visitor_home_areas type is specified in the origin_area_type column. 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:Int} {"360610112021": 603, "460610112021": 243, "560610112021": 106, "660610112021": 87, "660610112021": 51}
weekday_device_home_areas This column is the same as device_home_areas except it only includes those devices that stopped in the area Monday through Friday local time. These devices might have stopped in the area on other days as well but they at least stopped in the area on these days. JSON {String:Int} {"130890212162":91,"131210101101":22,"131350502123":20}
weekend_device_home_areas This column is the same as visitor_home_areas except it only includes those visitors that visited on Saturday or Sunday local time. These visitors might have visited on other days as well but they at least visited on these days. JSON {String:Int} {"130890212162":91,"131210101101":22,"131350502123":20}
breakfast_device_home_areas This column is the same as the device_home_areas except it only includes those devices that stopped in the area between 6 am and 10:59 am local time. These devices might have stopped in the area at other times as well but they at least stopped in the area during this time period. JSON {String:Int} {"130890212162":91,"131210101101":22,"131350502123":20}
lunch_device_home_areas This column is the same as device_home_areas except it only includes those devices that stopped in the area between 11 am and 2:59 pm local time. These devices might have stopped in the area at other times as well but they at least stopped in the area during this time period. JSON {String:Int} {"130890212162":91,"131210101101":22,"131350502123":80}
afternoon_tea_device_home_areas This column is the same as device_home_areas except it only includes those devices that stopped in the area between 3 pm and 4:59 pm local time. These devices might have stopped in the area at other times as well but they at least stopped in the area during this time period. JSON {String:Int} {"130890212162":91,"131210101101":82,"131350502123":25}
dinner_device_home_areas This column is the same as device_home_areas except it only includes those devices that stopped in the area between 5 pm and 8:59 pm local time. These devices might have stopped in the area at other times as well but they at least stopped in the area during this time period. JSON {String:Int} {"130890212162":91,"131210101101":82,"131350502123":25}
nightlife_device_home_areas This column is the same as device_home_areas except it only includes those devices that stopped in the area between 9 pm and midnight local time. These devices might have stopped in the area at other times as well but they at least stopped in the area during this time period. JSON {String:Int} {"130890212162":91,"131210101101":82,"131350502123":25}
work_hours_device_home_areas This column is the same as device_home_areas except it only includes those devices that stopped in the area between 7:30 am and 5:30 pm Monday through Friday local time. These devices might have stopped in the area at other times as well but they at least stopped in the area during this time period. JSON {String:Int} {"130890212162":91,"131210101101":22,"131350502123":80}
device_daytime_areas This column lists all the primary daytime origin areas for devices that stopped in this area. The number mapped to each primary daytime origin area is the number of devices observed with this primary daytime area where daytime is 9 am - 5 pm, and the device_daytime_areas type is specified in the origin_area_type column. 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:Int} {"131210101101":987,"131210119002":450,"131210101151":447,"130890212163":396,"131210116211":300,"130670302292":282,"130590004023":278,"131350503103":261,"131210100011":251,"130890212023":247,"131210019002":246,"131210116113":230,"131350503082":207,"130890212103":206,"131210101233":201,"131210116153":198,"131210010012":185,"130890224022":185,"131350503061":183,"131210102043":182,"130890212092":182,"131210010021":177,"131210101222":169,"131210101211":167,"131210100023":166,"131350502121":156,"131210115031":143,"131210102062":142,"130670303321":141,"131210101133":138,"131210116143":137,"130890212091":136,"130670303201":136,"131350502151":131,"131210005001":129,"131210116253":124,"130670303391":124,"131210114211":122,"130670308002":120, ... , ... ,"131350502131":50}
distance_from_home Median distance from home traveled to the stopping point(s) within the area by devices from their home area (of devices whose home area we have identified) in meters. If we have not identified a home area for at least 5 devices, distance_from_home will be blank. We determine home within 100 meters and we find the median distance per device (if more than one stop in the area for a device) and then find the median for all devices. Integer 29385
distance_from_primary_daytime_location Median distance from device_daytime_areas traveled to the stopping point(s) within the area by devices from their device_daytime_area (of devices whose device_daytime_area we have identified) in meters. If we have not identified a device_daytime_area for at least 5 devices, distance_from_primary_daytime_location will be blank. We determine device_daytime_area within 100 meters and we find the median distance per device (if more than one stop in the area for a device) and then find the median for all devices. Integer 29385
median_dwell Median dwell time in minutes. Note that we are only including stops that have a dwell of at least 1 minute. Double 5
top_same_day_brand Brands that the devices that stopped in this area visited in the same day as the stop in this area. Limited to top 20. The value shown for each brand is a percentage representing: devices going to both the brand and the area / total devices stopping in the area. JSON {String: Integer} {"mcdonalds": 7,"amc": 5,"target": 3}
top_same_month_brand Brands that the devices that stoppeed in this area visited in the same month as the stop in this area. Limited to top 20. The value shown for each brand is a percentage representing: visitors to both the brand and the area / total visitors to the area JSON {String: Integer} {"mcdonalds": 7,"amc": 5,"target": 3}
popularity_by_hour_monday A mapping of hour of the day to the number of stops that occurred in each hour on any Monday in the time range. Array [9877,8233,7520,7512,7992,11259,19885,29153,31278,34235,36753,41983,48438,48909,47167,48258,48485,47134,43544,37033,29193,22308,16456,12628]
popularity_by_hour_tuesday A mapping of hour of the day to the number of stops that occurred in each hour on any Tuesday in the time range. Array [9877,8233,7520,7512,7992,11259,19885,29153,31278,34235,36753,41983,48438,48909,47167,48258,48485,47134,43544,37033,29193,22308,16456,12628]
popularity_by_hour_wednesday A mapping of hour of the day to the number of stops that occurred in each hour on any Wednesday in the time range. Array [9877,8233,7520,7512,7992,11259,19885,29153,31278,34235,36753,41983,48438,48909,47167,48258,48485,47134,43544,37033,29193,22308,16456,12628]
popularity_by_hour_thursday A mapping of hour of the day to the number of stops that occurred in each hour on any Thursday in the time range. Array [9877,8233,7520,7512,7992,11259,19885,29153,31278,34235,36753,41983,48438,48909,47167,48258,48485,47134,43544,37033,29193,22308,16456,12628]
popularity_by_hour_friday A mapping of hour of the day to the number of stops that occurred in each hour on any Friday in the time range. Array [9877,8233,7520,7512,7992,11259,19885,29153,31278,34235,36753,41983,48438,48909,47167,48258,48485,47134,43544,37033,29193,22308,16456,12628]
popularity_by_hour_saturday A mapping of hour of the day to the number of stops that occurred in each hour on any Saturday in the time range. Array [9877,8233,7520,7512,7992,11259,19885,29153,31278,34235,36753,41983,48438,48909,47167,48258,48485,47134,43544,37033,29193,22308,16456,12628]
popularity_by_hour_sunday A mapping of hour of the day to the number of stops that occurred in each hour on any Sunday in the time range. Array [9877,8233,7520,7512,7992,11259,19885,29153,31278,34235,36753,41983,48438,48909,47167,48258,48485,47134,43544,37033,29193,22308,16456,12628]
device_type The number of devices that stopped in the area that are using android vs. ios. JSON {String: Integer} {"android": 6, "ios": 8}
iso_country_code The 2 letter ISO 3166-1 alpha-2 country code of the area. String US
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 MD

Along with the Neighborhood Patterns file, we also deliver Panel Overview Data (see below) to help you better understand the context of the data appearing in Neighborhood Patterns. In particular, the size of the panel of devices changes from month to month, so understanding the make-up of the panel helps to normalize stop counts over time.

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

Updated a day ago


Neighborhood Patterns


Suggested Edits are limited on API Reference Pages

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