Weekly Patterns

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:

Weekly Patterns Schema

[patterns.csv]

Column NameDescriptionTypeExample
placekeyUnique and persistent ID tied to this POI. See the Placekey Key Concept for details on placekey design.String[email protected]
parent_placekeyIf place is encompassed by a larger place (e.g. mall, airport), this lists the placekey of the parent place; otherwise null. See more on parent-child relationships in Spatial Hierarchy.String[email protected]
location_nameThe name of the place of interest.StringSalinas Valley Ford Lincoln
street_addressStreet address of the place of interest.String1100 Auto Center Circle
cityThe city of the point of interest.StringIrvine
regionThe state, province or county of the place of interest. See region.StringCA
postal_codeThe postal code of the place of interest.String92602
iso_country_codeThe 2 letter ISO 3166-1 alpha-2 country code.StringUS
safegraph_brand_idsUnique and consistent ID that represents this specific brand.ListSG_BRAND_59dcabd7cd2395a2, SG_BRAND_8310c2e3461b8b5a
brandsIf this POI is an instance of a larger brand that we have explicitly identified, this column will contain that brand name. See: brands.ListFord, Lincoln
date_range_startStart 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. Monday in local time.String2020-03-02T00:00:00-06:00
date_range_endEnd 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 Monday at 12 a.m. local time.String2020-03-09T00:00:00-06:00
raw_visit_countsNumber of visits in our panel to this POI during the date range. See raw_visit_counts.Integer1542
raw_visitor_countsNumber of unique visitors from our panel to this POI during the date range.Integer1221
visits_by_dayThe number of visits to the POI each day (local time) over the covered time period. See visits_by_day.JSON [Integer][33, 22, 33, 22, 33, 22, 22]
visits_by_each_hourThe number of visits to the POI for each of the 168 hours of the week, starting at midnight on date_range_start. See visits_by_each_hour.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_cbgThe census block group (U.S.) or dissemination area (Canada) the POI is located within.String560610112022
🛡 visitor_home_cbgsThe number of visitors to the POI from each census block group or dissemination area based on the visitor's home location. See visitor_home_cbgs.JSON {String: Integer}{"360610112021": 603, "460610112021": 243, "560610112021": 106, "660610112021": 87, "660610112021": 51}
🛡 visitor_home_aggregationThe number of visitors to the POI from each census tract or aggregate dissemination area based on the visitor's home location. See visitor_home_aggregation.JSON {String: Integer}{"17031440300": 1005, "18089021500": 522, "17197883516": 233, "17031826402": 5, "17031826301": 4, "04013115802": 4}
🛡 visitor_daytime_cbgsThe number of visitors to the POI from each census block group or dissemination area based on primary daytime location between 9 am - 5 pm. See visitor_daytime_cbgs.JSON {String: Integer}{"360610112030": 9872, "880610112021": 8441, "569610112020": 5671, "160610112041": 2296, "980610112021": 1985}
🛡 visitor_country_of_originThe number of visitors to the POI from each country based on visitor's home country code. See visitor_country_of_origin.JSON {String: Integer}{"US": 98,"CA": 12}
distance_from_homeMedian distance from home travelled by visitors (of visitors whose home we have identified) in meters. See distance_from_home.Integer1211
median_dwellMedian minimum dwell time in minutes. See median_dwell.Double5
bucketed_dwell_timesThe distribution of visit dwell times based on pre-specified buckets. Key is the range of dwell time in minutes and value is number of visits that were within that range. See bucketed_dwell_times.JSON {String: Integer}{ "<5": 40, "5-20": 22, "21-60": 45, "61-240": 3,">240": 5}
related_same_day_brandOther brands that the visitors to this POI visited on the same day as the visit to this POI. Limited to top 20. See related_same_day_brand.JSON {String: Integer}{"mcdonalds": 7,"amc": 5,"target": 3}
related_same_week_brandOther brands that the visitors to this POI visited in the same week as the visit to this POI. Limited to top 20. See related_same_week_brand.JSON {String: Integer}{"mcdonalds": 7,"amc": 5,"target": 3}
🛡 device_typeThe number of visitors to the POI that are using Android vs. iOS. See device_type.JSON {String: Integer}{"android": 6, "ios": 8}
🛡 †carrier_nameThe number of visitors to the POI based on the wireless carrier of the device. See carrier_name.JSON {String: Integer}{"Verizon": 342, "T-Mobile": 288, "AT&T": 265}

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

Column NameDescriptionTypeExample
date_range_startStart 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.String2020-03-01T00:00:00-06:00
date_range_endEnd 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.String2020-03-08T00:00:00-06:00
regionLowercase abbreviation of U.S. state or territory, or the Canadian Province or territory, depending on iso_country_codeStringny
iso_country_codeThe 2 letter ISO 3166-1 alpha-2 country code.StringUS
census_block_groupUS FIPS code for this Census block group, or the Canadian Dissemination area designation (Canadian units have CA: as a prefix)String530330080012
number_devices_residingNumber of distinct devices observed with a primary nighttime location in the specified census block group.Integer54481
number_devices_primary_daytimeNumber of distinct devices observed with a primary daytime location in the specified census block group.Integer54482

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

Column NameDescriptionTypeExample
starting_yearCalendar year that the first day of the weekly data is inInteger2018
starting_monthCalendar month that the first day of the weekly data is inInteger1
starting_dayCalendar day of the first day of the weekly dataInteger1
regionLowercase abbreviation of U.S. state or territory, or the Canadian Province or territory, depending on iso_country_codeStringny
iso_country_codeThe 2 letter ISO 3166-1 alpha-2 country code.StringUS
num_visitsNumber of point-of-interest visits observed in the specified stateInt8900
num_unique_visitorsNumber of unique visitors observed with at least 1 point-of-interest visit in the specified stateInteger966

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

Column NameDescriptionTypeExample
yearCalendar yearInteger2018
monthCalendar month starting from 1 as JanuaryInteger1
dayCalendar dayInteger1
regionWhen 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.StringCA
iso_country_codeThe 2 letter ISO 3166-1 alpha-2 country code.StringUS
total_visitsAll visits we saw on the given day in local time (includes visits to POI and visits to homes)Integer200
total_devices_seenTotal devices in our panel which we saw on the given day with any visit in local time (POI or home visit)Integer50
total_home_visitsVisits we saw on the given day in local time to the device's home geohash-7Integer120
total_home_visitorsTotal devices we saw on the given day with at least 1 visit to the device's home geohash-7Integer35

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

Release Metadata

[release_metadata.csv]

Column NameDescriptionTypeExample
metadata_descriptionDescription of piece of metadataStringcore_places_version_used
metadata_valueValue of applicable metadataString05-2020

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, to enable more frequently delivery of actionable data. (Note that 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 Core 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

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

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

visitor_country_of_origin

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.

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.

Carrier

Count

Ratio

Verizon

10,303,871

35.64%

AT&T

7,267,146

25.13%

T-Mobile

7,129,894

24.66%

Sprint

3,685,988

12.75%

Altice

323,221

1.11%

C-Spire

204,800

0.71%

Known Data Issues or Artifacts

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


Did this page help you?