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