Submitting Data to Observation Graph — Accepted Data Format
Data partners submitting mobile location data to Factual for Observation Graph processing will need to adhere to our standard JSON data format. Please read below for more details on how to deliver and format the data.
Delivery
Your 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.5.
Required Fields
The following fields must be submitted for Factual to process data:
Field | Type | Description | Example |
---|---|---|---|
timestamp | float | Number of milliseconds since the Unix epoch — 00:00:00 UTC on 1 January 1970. | 1506815998000 |
payload.device.ifa | string | ID sanctioned for advertiser use in the clear (e.g., Apple’s IDFA, Android’s Advertising ID). | “f66f31a5-461c-441a-a48e-582351763349” |
payload.device.geo.lat | float | Latitude of device, with full coordinate precision as reported by OS. | 39.86178942493401 |
payload.device.geo.lon | float | Longitude of device, with full coordinate precision as reported by OS. | -75.50972699060499 |
payload.app.id or payload.app.name or payload.app.bundle | string | A way to uniquely identify the app from which the input came, where payload.app.id is a partner-specific identifier of some kind, payload.app.name is a human readable app name, and payload.app.bundle is the OS specific bundle or package name of the app (e.g., on iOS the bundle ID is a numeric ID; on Android, the bundle ID is the package name like com.foo.mygame). At least one of these app identifiers is required, while the remaining app identifiers are highly recommended. | “Ab123” or “My Social App” or “com.foo.mygame” |
Required Fields — If Available from Partner
The following fields are fields that are required if the partner has access to them:
Field | Type | Description | Example |
---|---|---|---|
payload.device.geo.accuracy | float | Horizontal accuracy, in meters, as reported by the OS. | 10.1 |
payload.device.geo.ext.speed | float | Speed, in meters per second, as reported by the OS. | 1.0 |
payload.device.geo.ext.orientation | float | Orientation of device, in degrees clockwise from north, as reported by the OS. | 349.1 |
payload.device.geo.ext.alt | float | Altitude, in meters, as reported by the OS. | 100.5 |
payload.device.geo.ext.altaccuracy | float | Altitude accuracy, in meters, as reported by the OS. | 4.2 |
payload.device.make | string | Device make. | “Apple” |
payload.device.model | string | Device model. | “iPhone” |
payload.device.os | string | Device operating system. | “iOS” |
payload.device.osv | string | Device operating system version. | “6.1” |
payload.device.language | string | Device current language using ISO-639-1. | “en” |
payload.device.carrier | string | Carrier. | “VERIZON” |
Recommended Fields
The following fields are highly recommended fields that should also be submitted whenever possible:
Field | Type | Description | Example |
---|---|---|---|
payload.device.geo.ext.appstate | string | Runtime state of the app when the event occured, where value should be one of: “foreground”, “background”, “unknown” | “background” |
payload.device.geo.type | integer | Source of location data. Refer to List 5.20 of the OpenRTB 2.5 spec. | 1 |
payload.device.connectiontype | integer | Network connection type. Refer to List 5.22 of the OpenRTB 2.5 spec. | 2 |
payload.device.ext.ssid | string | Wifi SSID. | “My Network” |
payload.device.ext.bssid | string | Wifi BSSID. | “24:a4:d7:a2:1b:91” |
payload.device.geo.ext.floorlevel | integer | Floor of the building on which the device is located, as reported by the OS. | 1 |
payload.device.geo.ext.durationmins or payload.device.geo.ext.durationms | float | The dwell time that the device spent at the associated location. This can be detected using the OS platform’s native location services. This should only be passed on input signals that are associated with the device’s exit (or egress) from the location. The durationmins field represents the dwell time in minutes and the durationms field represents the dwell time in milliseconds. One or both may be passed. | 35 or 2136000 |
payload.device.ip | string | IPv4 address closest to device. | “123.145.167.189” |
payload.device.ipv6 | string | IP address closest to device as IPv6. | “0:0:0:0:0:FFFF:7B91:A7BD” |
payload.device.ua | string | User agent string. | “Mozilla/5.0 (iPhone; CPU iPhone OS 10_2 like Mac OS X) AppleWebKit/602.3.12 (KHTML, like Gecko) Mobile/14C92” |
Example Record
The following is an example of a compliant input record:
{
"timestamp":1441738238412,
"payload":{
"app":{
"id":"abcd",
"name":"My Streaming App",
"bundle":"12345"
},
"user":{
"id":"1234567890abcdef"
},
"device":{
"ifa":"a70a25da-0649-498e-9374-2d237f45c108",
"ext":{
"ssid":"XYZ network",
"bssid":"24:a4:d7:a2:1b:91"
},
"language":"en",
"os":"Android",
"osv":"6.0",
"make":"Samsung",
"model":"SM-T560NU",
"carrier":"Verizon Wireless",
"connectiontype":2,
"ip":"123.145.167.189",
"ipv6":"0:0:0:0:0:FFFF:7B91:A7BD",
"ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 10_2 like Mac OS X) AppleWebKit/602.3.12 (KHTML, like Gecko) Mobile/14C92",
"geo":{
"lat":39.86178942493401,
"lon":-75.50972699060499,
"accuracy":10.1,
"type":1,
"ext":{
"appstate":"background",
"alt":100.5,
"altaccuracy":4.2,
"speed":1.0,
"orientation":349.1,
"floorlevel":1
}
}
}
}
}
Updated almost 3 years ago