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