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