Submitting Audience Data – Accepted Formats

If you’re using a file-based method of submitting Audience data to Factual, your files must conform to our standard JSON data format. Please read below for more details on how to deliver and format the data.

Delivery

You upload files must be compressed with gzip and the file names must end in “.gz”. Individual records should be delimited by a newline.

JSON Format

The format of the uploaded files must be line-delimited JSON objects with two top-level fields: timestamp and payload. timestamp indicates the time of the event, and payload contains event data in a format compatible with OpenRTB 2.2.

Summary of Required Fields

The following are the minimum fields required to build Audience segments from submitted data:

  • A timestamp field, .timestamp, containing a number representing the number of milliseconds since the Unix epoch — 00:00:00 UTC on 1 January 1970.
  • A latitude field, .payload.device.geo.lat, containing a number representing the latitude.
  • A longitude field, .payload.device.geo.lon, containing a number representing the longitude.
  • A user identifer field, which must be one of the following strings:
  • .payload.device.ext.idfa, if the ID provided is an ID for advertisers (Apple IDFA or Android Advertising ID).
  • .payload.device.dpidsha1, if the ID provided is a SHA-1 hash of a device identifier.
  • .payload.user.id, if the ID is any other type of device identifier.
  • Factual accepts additional OpenRTB fields. See the OpenRTB 2.2 specification for more details.

Supported Extensions

Factual supports the following extension fields in the OpenRTB payload:

Field

Scope

Type

Description

Example

payload.device.geo.ext.accuracy

Recommended

float

Geo accuracy, in meters

10.1

payload.device.ext.ssid

Recommended

string

WIFI SSID

"My Network"

payload.device.ext.bssid

Recommended

string

WIFI BSSID

"24:a4:d7:a2:1b:91"

payload.device.geo.ext.speed

Recommended

float

Speed, in meters per second

0.0

payload.device.geo.ext.orientation

Recommended

float

Orientation of device, in degrees clockwise from north

349.1

payload.device.geo.ext.alt

Recommended

float

Altitude, in meters

100.5

payload.device.geo.ext.altaccuracy

Recommended

float

Altitude accuracy, in meters

4.2

Example Records

The following is an example of two compliant input records. Note that each is providing additional optional fields from the OpenRTB spec (scroll to see full line).

{"timestamp": 1441736244578,"payload": {"device": {"ext": {"idfa": "ce758862-9f71-4d78-afab-37688bb2fe18"},"language": "en","os": "Android5.0.1","geo": {"lat": 37.31207387,"lon": -120.77605476,"ext": {"activity": "walking","verified_location_id": "bc060887-dc48-4a88-8b5e-793ec3893341"}}}}}
{"timestamp": 1441738238412,"payload": {"app": {"id": "51121664-868c-af0d-2229-d4995c33bebf"},"device": {"ext": {"idfa": "a70a25da-0649-498e-9374-2d237f45c108"},"language": "en","os": "Android5.1.1","geo": {"lat": 39.27172509,"lon": -86.6257966},"ip": "70.194.62.225"}}}