MD: Receiving Measurement Data TSV Files
Factual's Measurement Data solution sends store visits to partner platforms like DSPs, campaign management systems, and marketing intelligence platforms. These platforms in turn use that data in their attribution methodology and provide reporting on store visit conversions.
This document describes the file format details of Measurement Data for any platforms receiving this data through an s3 integration.
For s3 integration partners, Factual delivers Measurement Data on a nightly cadence as TSV batch files containing all store visit data that was processed on that day. The TSV files will use UTF-8 text encoding and rows will be separated by newlines (\n
line endings).
column | description | null value (when no value is available) |
---|---|---|
Device ID | Device ID | |
Timestamp | Timestamp in seconds (Unix epoch time), granular to the hour | |
Store ID | Either the supplied location ID or the Factual ID for this visit | |
Dwell Time | Dwell time (a.k.a. duration) in seconds | - |
Distance from home - lower limit† | Lower limit of the 1-mile range encompassing the distance from home for this visit | - |
Distance from home - upper limit† | Upper limit of the 1-mile range encompassing the distance from home for this visit | - |
Distance from work - lower limit† | Lower limit of the 1-mile range encompassing the distance from work for this visit | - |
Distance from work - upper limit† | Upper limit of the 1-mile range encompassing the distance from work for this visit | - |
† The fields related to distance from home
and distance from work
represent ranges in 1-mile increments. For example, if a visit represented a distance of 5.13 miles from home and 8.26 miles from work, then that visit record would have the following values:
- distance from home - lower limit = 5
- distance from home - upper limit = 6
- distance from work - lower limit = 8
- distance from work - upper limit = 9
For the dwell time
, distance from home
and distance from work
fields, in cases where we do not have enough data to produce values for those fields, a null value (-
) will be used. Also, in cases where the device resides in a very low populated area, a null value will be used for the distance from home
fields.
Example Rows
Campaign B uses the 8-column TSV file format. Each record shows Device ID
, Timestamp
, Store ID
, Dwell Time
, Distance from home - lower limit
, Distance from home - upper limit
, Distance from work - lower limit
and Distance from work - upper limit
. The output file contains:
deviceid1 1542733200 place1 1200 5 6 8 9
deviceid1 1542740400 place2 - 1 2 4 5
deviceid2 1542826800 place2 2000 - - - -
Note that for the second row, we recorded a visit but did not have a dwell time. And for the third row, we recorded a visit but did not have distance from home or distance from work ranges.
Factual Places Mapping File
For campaigns that leverage Factual Places, Factual will send a tab-delimited place mapping file that contains attributes about the measured places. The standard attributes we offer for measurement are as follows:
Column | Description |
---|---|
Factual ID | Unique identifier |
Name | Business/POI name |
Locality | City, town or equivalent |
Region | State, province, territory, or equivalent |
Postcode | Postcode or equivalent (zipcode in US) |
Country | ISO 3166-1 alpha-2 country code |
Category Label | Category labels that describe the category branch |
Chain Name | Label indicating which chain (brand or franchise) this entity is a member of. |
Below are a few sample rows:
24f4dc96-3a90-4950-858c-60410f436daf Starbucks Highland Park IL 60035 us [["Social","Food and Dining","Cafes, Coffee and Tea Houses"]] Starbucks
c3e9ea11-a597-477e-a6fd-cd62952fc279 Starbucks Des Plaines IL 60018 us [["Social","Food and Dining","Cafes, Coffee and Tea Houses"]] Starbucks
d7bdcaa3-e521-4e48-aa37-771401daea28 Starbucks Glenview IL 60025 us [["Social","Food and Dining","Cafes, Coffee and Tea Houses"]] Starbucks
dfdc5ce3-b8c4-4c53-9f1d-e3434e1d1d98 Starbucks Chicago IL 60605 us [["Social","Food and Dining","Cafes, Coffee and Tea Houses"]] Starbucks
04bc64f6-e264-41b3-83b2-817cca4ab7ed Starbucks Bolingbrook IL 60440 us [["Social","Food and Dining","Cafes, Coffee and Tea Houses"]] Starbucks
0cf5bc61-2c7d-44d1-b3c4-9edb5c97d91b Starbucks Chicago IL 60601 us [["Social","Food and Dining","Cafes, Coffee and Tea Houses"]] Starbucks
489b690c-d8bb-43a9-90a7-15bad5a78440 Starbucks Naperville IL 60564 us [["Social","Food and Dining","Cafes, Coffee and Tea Houses"]] Starbucks
Legacy Version of Measurement Data
For campaigns configured using our first version of Measurement Data, TSV files will use a 3-column format with the following tab-separated columns in fixed order:
column | description |
---|---|
Device ID | Device ID |
Timestamp | Timestamp in seconds (Unix epoch time), granular to the hour |
Store ID | Either the supplied location ID or the Factual ID for this visit |
Example Using Legacy Version
Campaign A uses the 3-column TSV file format. Each record shows Device ID
, Timestamp
and Store ID
. The output file contains:
deviceid1 1542733200 place1
deviceid1 1542740400 place2
deviceid2 1542826800 place2
Updated over 3 years ago