Location Data IN Specifications

Last Updated January 4, 2019

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:

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. “ 66.249.66.53 ”.

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

altitude

vertical_accuracy

speed iOS = CLLocationSpeed ; Android = getSpeed

course_bearing  iOS = CLLocationDirection ; Android = getBearing

device_model  Android = android.os.Build.Model

os_version

device_language  iOS = NSLocale preferredLanguages ; Android = getDisplayLanguage

*user_agent

How satisfied are you with this article?

  • Not at all satisfied
  • 1
  • 2
  • 3
  • 4
  • 5
  • Completely satisfied