Weekly Patterns

❗️

Legacy Product

This page references SafeGraph Patterns, Weekly Patterns, and/or Neighborhood Patterns, legacy products that will no longer be available at the start of 2023. If you are interested in foot traffic data, please contact us and we can refer you to a mobility data partner.

SafeGraph’s Weekly Patterns data provides the same foot traffic data insights from Patterns on a weekly basis, tracking data from Monday to the end of day on Sunday each week. Weekly patterns are available starting from January 1st, 2018 and include information on visits_by_each_hour and more!

Contents:

• Schema
• Key Concepts
• Column Details
• Data Issues or Artifacts

Weekly Patterns Schema

patterns.csv [reference file name for enterprise deliveries]

🛡 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. See more on privacy here.

† carrier_name is a premium column. Please Contact Sales for more details.

Panel Overview Data

Along with the Weekly Patterns file, we also deliver Panel Overview Data (see tables below) to help you better understand the context of the data appearing in Weekly Patterns.

Home Location Distributions by State/Census Block Group

[home_panel_summary.csv]

Number of Visits/Visitors by State

[visit_panel_summary.csv]

Note: Includes three row designated ALL_US, ALL_CA, and ALL to provide total visitors seen during the week in the US, in Canada, and in both countries (might be less than sum of visitors by state due to same visitors having visits in multiple states).

Normalization Stats

[normalization_stats.csv]

We also provide a file containing information on our panel for each day of the week to help with normalization. This file will have rows for each region for each day of the week.

Note: This includes the ALL_US, ALL_CA, and ALL rows similar to visit_panel_summary.csv

Lastly, each delivery of Weekly Patterns contains a metadata file about the release itself.

Release Metadata

[release_metadata.csv]

The current metadata we include:

• core_places_version_used
• total_poi
• total_branded_poi

Key Concepts

Weekly Patterns uses the same logic as our normal Patterns product for key concepts such as Geographic Bias, Visit Attribution, Determining Home Location, Privacy, and Backfills, and more. The best way to think about the two products is that the underlying visits and algorithms are the same, but they are aggregated at different timescales and delivered at difference frequencies.

Below are some differences between Weekly Patterns and Patterns:

1. Each delivery of Weekly Patterns covers one week starting Monday and ending end of day on Sunday. The data will be available three days later on Wednesday of each week, providing more frequent actionable data.
   (Note: A very early, now deprecated, version of Weekly Patterns (v1) went from Sunday to end of day Saturday and was delivered on Tuesdays)
2. We have Weekly Patterns starting from January 1, 2018. For historical beyond that, the regular Patterns file should be used.
3. In Weekly Patterns, we include a visits_by_each_hour column to enable you to get a more detailed view of the week.
4. Weekly Patterns does not include popularity_by_hour (covered by visits_by_each_hour) and popularity_by_day (covered by visits_by_each_hour).
5. We update our Places file monthly and start using the new file for our visits generation on the first of each calendar month. This means that if we introduce a new place on the 1st of a month and the Weekly Patterns file straddles two months, you will only see visits for the new place in those days of the week that are in the new month. This edge case only affects a tiny fraction of places each month.
6. Weekly Patterns is also the only product where Canada foot traffic data is available. This means there are also some subtle changes to how columns behave and names of columns that make it distinct from the Monthly Patterns product (e.g., the state column in Supplemental Files is named region in Weekly Patterns).

Column Name Detailed Descriptions

street_address

• We implement a number of steps to clean, validate and standardize street_address.
• You should expect street_address to be title-cased, consistent, and friendly for human reading. Please send us your feedback if you see otherwise.
• If you care about street addresses as much as we do, we also have more specific address columns to split out address components. These are optional and available upon request for future deliveries.
  • primary_number
  • street_predirection
  • street_name
  • street_postdirection
  • street_suffix

city

• In the US, all centroids (latitudes/longitudes) are referenced against a geospatial file of city boundaries as defined by the US Census Bureau (browse the boundaries here). In edge cases, the preferred city name in the address line reflects a pre-annexed city name, and we try our best to preserve those city names where possible.
• In Canada, city names are the output of normalized address strings from POI sources.
• In Great Britain, city names are the output of normalized address strings from POI sources, but in edge cases, we allow POIs to have a null city name as long as region is populated. The region column in Great Britain refers to county boundaries, and counties are a decent alternative to cities for geographic filtering.

region

• When iso_country_code == US, then this is the US state or territory.
• When iso_country_code == CA, then this is the Canadian Province or territory.
• When iso_country_code == GB, then this is the United Kingdom county.

postal_code

• When iso_country_code == US, then this is the US 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).
• When iso_country_code == GB, then this is the British postal code. Learn more about Great Britain postal code precision here.

raw_visit_counts

These are the aggregated raw counts that we see visit the POI from our panel of mobile devices. The duration of the visit must last at least 4 minutes to count as a visit to a given POI.

visits_by_day

• This is an array of visits on each day in the week, Monday through Sunday.
• We are breaking up days based on local time.
• See also: How do I work with Patterns columns that contain JSON?

visits_by_each_hour

• This is an array of visits for each hour that exists in the week.
• Only the start of a visit is used for this column so multi-hour visits will only be counted once unless the visit crosses a UTC day boundary. Note that this is a subtle difference compared to how popularity_by_hour is calculated in Monthly Patterns
• We are breaking up days based on local time.
• See also: How do I work with Patterns columns that contain JSON?

visitor_home_cbgs

• These are the home census block groups (U.S.) or dissemination areas (Canada) of the visitors to the POI.
• For each census block group, we show the number of associated visitors (as opposed to the number of visits). If visits by home cbg is desired, we recommend taking the visitors from each CBG and multiplying by the average visits/visitor (i.e., raw_visit_counts / raw_visitor_counts) as an approximation.
• We do not have a home census block group for each visitor and not each visitor originates from the US. The number of US visitors listed in the visitor_country_of_origin column represents the total number of visitors which we have determined originate from the US versus Canada.
• See also: How do I work with Patterns columns that contain JSON?, Determining Home Location and Privacy.

visitor_home_aggregation

• This is similar to visitor_home_cbgs except they represent the home census tracts (U.S.) or aggregate dissemination areas (Canada) of the visitors to the POI.
• We recommend using this column when you do not need to know visitor homes areas at such a fine level (CBGs represent 600-3000 people while DAs represent 400-700), but can aggregate to the next-level-up geographic unit (CTs represent 2,500 to 8,000 people while ADAs represent 5,000 to 15,000).

visitor_daytime_cbgs

• These are the daytime census block groups of the visitors to the POI.
• For each census block group, we show the number of associated visitors (as opposed to the number of visits).
• See also: How do I work with Patterns columns that contain JSON?, Determining Home Location and Privacy.

visitor_country_of_origin

• These are the countries of origin of the visitors to the POI.
• See also: How do I work with Patterns columns that contain JSON?, Determining Home Location and Privacy.

distance_from_home

• This is the median distance from home to the POI in meters for the visitors we have identified a home location.
• This is calculated by taking the haversine distance between the visitor's home geohash-7 and the location of the POI for each visit. We then take the median of all of the home-POI distance pairs.
• If we have fewer than 5 visitors to a POI, the value will be null.
• We do not adjust for visits - each visitor is counted equally.

median_dwell

• This is the median of the minimum dwell times we have calculated for each of the visits to the POI.
• We determine the minimum dwell time by looking at the first and last ping we see from a device during a visit. This is a minimum dwell because it is possible the device was at the POI longer than the time of the last ping.
• It is possible to have a minimum dwell of 0 if we only saw 1 ping and determined the visit based on factors such as wifi.

bucketed_dwell_times

• This is a dictionary of different time spans and the number of visits that were of each duration.
• The time spans are in minutes.
• Data delivered from December 2020 onward, including all backfilled historical data, contains the following bins: { "<5", "5-10", "11-20", "21-60", "61-120", "121-240", ">240"}
• Data delivered prior to December 2020 contains the following bins: { "<5", "5-20", "21-60", "61-240", ">240"}
• See also: How do I work with Patterns columns that contain JSON?

related_same_day_brand

• These are the brands that the visitors to this POI also visit, on the same day that they visit the POI. The number mapped to each brand is an indicator of how highly correlated a POI is to a certain brand. The value is a simple percent of POI visitors that visited the other brand on the same day.
• Note that the way this column was calculated changed in data released in July 2021 and onward. At that time, all historical data since 2018 was re-computed with the new way of calculation. There should be no inconsistency if you are using the latest data.
• Only the first 20 brands are returned.
• See also: How do I work with Patterns columns that contain JSON?

related_same_week_brand

These are the brands that the visitors to this POI visit over the course of the week. Interpreted and calculated in the same way as related_same_day_brand.

• See also: How do I work with Patterns columns that contain JSON?

carrier_name

• This is a premium column that maps wireless carrier names to the number of visitors to the POI whose device uses that wireless carrier.
• Below is a breakdown of our panel of devices by wireless carrier as of the July-2020 release:
• See also: How do I work with Patterns columns that contain JSON? and Privacy.

Known Data Issues or Artifacts

See the Known Issues or Data Artifacts in Developer Tools for more information.