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