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:

FieldTypeDescriptionExample
timestampfloatNumber of milliseconds since the Unix epoch — 00:00:00 UTC on 1 January 1970.1506815998000
payload.device.ifastringID sanctioned for advertiser use in the clear (e.g., Apple’s IDFA, Android’s Advertising ID).“f66f31a5-461c-441a-a48e-582351763349”
payload.device.geo.latfloatLatitude of device, with full coordinate precision as reported by OS.39.86178942493401
payload.device.geo.lonfloatLongitude of device, with full coordinate precision as reported by OS.-75.50972699060499
payload.app.id or payload.app.name or payload.app.bundlestringA 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:

FieldTypeDescriptionExample
payload.device.geo.accuracyfloatHorizontal accuracy, in meters, as reported by the OS.10.1
payload.device.geo.ext.speedfloatSpeed, in meters per second, as reported by the OS.1.0
payload.device.geo.ext.orientationfloatOrientation of device, in degrees clockwise from north, as reported by the OS.349.1
payload.device.geo.ext.altfloatAltitude, in meters, as reported by the OS.100.5
payload.device.geo.ext.altaccuracyfloatAltitude accuracy, in meters, as reported by the OS.4.2
payload.device.makestringDevice make.“Apple”
payload.device.modelstringDevice model.“iPhone”
payload.device.osstringDevice operating system.“iOS”
payload.device.osvstringDevice operating system version.“6.1”
payload.device.languagestringDevice current language using ISO-639-1.“en”
payload.device.carrierstringCarrier.“VERIZON”

Recommended Fields

The following fields are highly recommended fields that should also be submitted whenever possible:

FieldTypeDescriptionExample
payload.device.geo.ext.appstatestringRuntime state of the app when the event occured, where value should be one of: “foreground”, “background”, “unknown”“background”
payload.device.geo.typeintegerSource of location data. Refer to List 5.20 of the OpenRTB 2.5 spec.1
payload.device.connectiontypeintegerNetwork connection type. Refer to List 5.22 of the OpenRTB 2.5 spec.2
payload.device.ext.ssidstringWifi SSID.“My Network”
payload.device.ext.bssidstringWifi BSSID.“24:a4:d7:a2:1b:91”
payload.device.geo.ext.floorlevelintegerFloor 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.durationmsfloatThe 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.ipstringIPv4 address closest to device.“123.145.167.189”
payload.device.ipv6stringIP address closest to device as IPv6.“0:0:0:0:0:FFFF:7B91:A7BD”
payload.device.uastringUser 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
            }
         }
      }
   }
}