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