Knowledge Base

MD: Integrating Factual Measurement Data via Amazon S3

Factual Measurement Data can be integrated directly via Amazon S3. This document details the S3 integration requirements. For the data schema, please see Receiving Measurement Data TSV Files.

S3 Permissioning

For direct S3 integrations, we ask partners to host an S3 bucket and issue us a set of credentials (access key and secret key). We require the following permissions:

s3:DeleteObject
s3:GetObject
s3:PutObject
s3:ListBucket
s3:GetBucketLocation

For more information on how to set up user permissions and issue credentials, please see this AWS article (How do I create an AWS access key?).

FIle Naming Convention

Our standard file naming convention is as follows, where brand and campaign name are provided by the partner and the YYYY-MM-DD date is the processed date:

s3://<bucketname>/<brand>/<campaign name>_visits_YYYY-MM-DD.tsv

Example directory listing below:

s3://factual_partner/AmysHardware/AmysHardware-Fall-Campaign_visits_2019-09-01.tsv
s3://factual_partner/AmysHardware/AmysHardware-Fall-Campaign_visits_2019-09-02.tsv
s3://factual_partner/AmysHardware/AmysHardware-Fall-Campaign_visits_2019-09-03.tsv
s3://factual_partner/AmysHardware/AmysHardware-Fall-Campaign_visits_2019-09-04.tsv

Factual Places Mapping File

In addition to receiving visit files on a regular cadence, Factual will provide a place mapping file that includes additional attributes about the measured places (if Factual Places are used). This is a one time delivery.

Naming Convention

The place mapping file will have the following naming convention:
s3://<bucketname>/<brand>/<campaign name>_places.tsv

Example:
s3://factual_partner/AmysHardware/AmysHardware-Fall-Campaign_places.tsv

Attributes Included

We offer the following standard attributes as part of our Measurement solution. To see our full attribute listing, please see Core Attributes. If you would like to receive any additional attributes that are listed in Core Attributes but not listed below, please reach out to your Factual account representative

  • Factual Place ID
  • Place Name
  • Locality (city)
  • Region (state)
  • Country
  • Category Label

Sample records:

factual_id    name    locality    region    country    category_label
00082a0d-35e4-404b-baf8-a616053da341	Dog	Clayton	CA	us	[["Social","Food and Dining","Restaurants"]]
0029e723-fb93-4cc3-a949-f861b0918cec	Marilyn's Malts & More	Ada	MI	us	[["Social","Food and Dining","Restaurants","Fast Food"]]
00315043-46fa-421d-b0ef-bfaea168f13c	Los Hermanitos	Farmington	NM	us	[["Social","Food and Dining","Restaurants","Mexican"],["Social","Food and Dining","Restaurants","Pizza"]]
004aa0d5-36c4-4e90-ad71-a7a1c00ab10c	Cafe Cabana	Lansdale	PA	us	[["Social","Food and Dining","Cafes, Coffee and Tea Houses"],["Social","Food and Dining","Restaurants"]]
0069493e-5684-4a67-9809-fb140ffa71c4	Schooner Saloon	Eureka	CA	us	[["Social","Bars"],["Social","Food and Dining","Restaurants"]]
0084e020-9ac3-4265-85ba-8547b47170dc	Ed's Place	Sulphur	LA	us	[["Social","Food and Dining","Restaurants"]]
00987180-8885-43a3-bdd5-eb5504adb482	Shoney's Pearl	Pearl	MS	us	[["Social","Food and Dining","Restaurants"]]
00a76de9-8d87-4aec-b4ee-ce110b65a619	Arosa Cafe	Seattle	WA	us	[["Social","Food and Dining","Restaurants","American"],["Social","Food and Dining","Cafes, Coffee and Tea Houses"]]
00deb876-a6a2-45e1-9a21-d92ee180c535	Subway	Bowie	MD	us	[["Social","Food and Dining","Restaurants","Fast Food"],["Social","Food and Dining","Restaurants","Delis"]]

Updated over 3 years ago