Data File Format
- Daily Gzipped .TSV files, ideally with each file not exceeding 1GB. Large datasets should be separated into multiple files (named part001, part002, etc…)
- Each row is an individual location record
- See below for data fields to include with each record (e.g. device_id, lat/long, etc…)
- If possible, please include a header row with column names in each TSV file. Exactly as written below
- Partner delivers location data to Sovrn SFTP /IN/location_data/
- File name should be: <yourcompanyname>_location_data_<YYYYMMDD>.tsv.gz
Data File Fields
Location data is of increasing value to the market to power sophisticated location-based ad targeting. However, the value varies based on how the data is collected
- Do not include any records of users who have limited ad tracking in Android or iOS or otherwise opted out of your system
- Deliveries should be made to the Sovrn SFTP daily.
- Use the following instructions to format your lines appropriately.
A line in your location file is thus formatted as follows:
<mobile_ad_id> <id_type> <timestamp> <latitude> <longitude> <ip_address> <horizontal_accuracy> <country_code> <location_context> <location_method> <altitude> <vertical_accuracy> <speed> <course_bearing> <device_model> <os_version> <device_language> <user_agent>
An actual line would look like this:
991af37c-8e8d-4b48-8686-9410833b9ffe<TAB>IDFA<TAB>1444951742000<TAB>36.269982<TAB>-121.808216<TAB>188.8.131.52<TAB>6<TAB>US<TAB>bground<TAB>gps<TAB>41<TAB>22<TAB>2<TAB>94<TAB><TAB>11.0<TAB><TAB>Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Mobile/15A372
Field Definition Required
Required Fields : If you do not send these fields, our process will reject your file
mobile_ad_id IDFA or AAID. This must be delivered in cleartext (unhashed).
id_type “IDFA” or “AAID”
timestamp Timestamp of the moment the observation was recorded. Must be in Unix Time in milliseconds, aka the number of milliseconds since “the epoch” (January 1, 1970, 00:00:00 GMT)
latitude With at least 4 decimal points of precision. Precision should reconcile with accuracy for each individual location point.
longitude With at least 4 decimal points of precision. Precision should reconcile with accuracy for each individual location point.
ip_address This value is the public /external IP address of the device that made the request, received on the server side. It must be in IPv4 format, e.g. “ 184.108.40.206 ”.
horizontal_accuracy This is the horizontal accuracy of the location point in meters. Sovrn will only accept records with a horizontal accuracy value of 50 or less.
country_code A two-digit country code, using the standard ISO-3166-1 format.
location_context This is an indicator for whether the particular device is delivering data in the foreground or background. Options are “fground” or “bground”.
location_method This is an indicator for the source of the particular signal. Options are “gps”, “cell”, or “ip”. Note that if “ip” is used, this must be the IP from a hotspot/wifi signal, not a look-up via a 3rd party IP to latitude/longitude service. Data collected solely or primarily through GPS will monetize the best.
Field Definition Optional
Please include these fields, if data is not available then leave the field blank. Append these columns after the required fields
*Highly recommended fields
speed iOS = CLLocationSpeed ; Android = getSpeed
course_bearing iOS = CLLocationDirection ; Android = getBearing
device_model Android = android.os.Build.Model
device_language iOS = NSLocale preferredLanguages ; Android = getDisplayLanguage