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