Data Partners (Batch)
GroundTruth is the leading location platform, helping app developers to monetize their location data, create location based services in their app, and understand their audience through their offline behavior.
You must first create an account with GroundTruth in order to proceed with the integration.
If you do not have an account, please contact your account manager, or send an email to: [email protected]
Overview
This document outlines how a partner can send user location signals to GroundTruth for interpretation of user location data. A partner can provide this information via uploading a file with multiple records on a daily basis.
Feasibility
Before integration, please communicate to our account manager / business development team member with an estimate number of rows per day to assess feasibility.
Data preparation
We have strict guidelines for certain fields that will allow our data pipelines to process all your data with minimum issues. The data will be sent over CSV files, so some basic understanding is required.
Mobile Applications Only
GroundTrust is not interested in any data from website or mobile website. So please make sure that all location data sent through this process are from mobile applications.
CSV Headers
The first line must contain the header. You must include all mandatory fields as well as any additional fields you can find in the addendum at the bottom of this document. Please make sure all the data and headers are aligned like a spreadsheet e.g. put date data under the date column.
Data Encoding
If there is no data for a given field on a given record please leave it empty, i.e. no space between the commas (,,).
Values in the file should be CSV escaped (a backslash before the comma).
Data Freshness
The exptimestamp of each record (row) must be within 96 hours of the time of upload.
Limited Country Support
We only support the following countries: US and CA. If you have additional data please inform us so we can explicitly enabled them.
Note: The country field is deprecated. Country is derived using the coordinates.
GDPR
We are adding two new fields to allow data vendors to pass along the status of the user as well as their consent to their data sharing. The two fields are gdpr and gdpr_consent. If the user is from the EU/EEA you must set gdpr to 1, otherwise set to 0. When from EU/EEA gdpr_consent must also have a value, if not keep the field blank, but gdpr_consent is still mandatory.
Mandatory Fields
Each file at a minimum must contain the following fields (can accept additional fields):
Field | Required | Description | Example |
|---|---|---|---|
recordtype | YES | 0 - Applications Due to exclusive interest in mobile applications, the field should only be populated with 0s | 0 |
exptimestamp | YES | UNIX timestamp of record | 1467843086186 |
id | YES | The bundle/name of the source providing the record. | com.appname |
os | YES | Operating system of the device: android ios If not in the list above, provide the name of the OS that the runtime environment provides | ios |
uid | YES | User's IDFA for iOS | 46ab0a92-8497-46dd-b70a-d640a225ec24 |
uidtype | YES | pass "IDFA" for iOS | IDFA |
lat | YES | User's latitude | 37.79867 |
lon | YES | User's longitude | -122.41762 |
ha | YES | Horizontal accuracy as it is read from the device GPS in meters. Convert to meters when device provides a different unit | 10 |
va | YES | Vertical accuracy as it is read from the device GPS in meters | 10 |
alt | YES | Device altitude | 200.9 |
speed | YES | Speed of device in MPH | 10 |
speedaccuracy | Yes (Android only) | Speed Accuracy (meters per second) | 1 |
direction | YES | An azimuth that is measured in degrees relative to north (course / bearing) | 90 |
directionaccuracy | Yes (Android only) | Estimated bearing accuracy of this location (degrees) | 10 |
floor | Yes (iOS only) | Floor in building device is located | 12 |
country | YES | (Deprecated) ISO country code where the device is located Supported values are "US", "CA", "GB", "DE" , "ES", "FR","JP","IT" and "IN" for United States, Canada, United Kingdom, Germany, Spain, France, Japan, and India respectively | us |
gdpr | YES | 0 - Not restricted by GDPR If user is located in EU/EEA then this field must be set to 1 | 0 |
gpdr_consent | YES | This is the IAB consent string which is a daisybit encoded in base64. Always have this column present even if gdpr=0, just keep the consent blank. | Y29uc2VudF9zdHJpbmc= |
lmt | YES | “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where: 0 - Tracking is unrestricted | 0 |
Supported Fields
Field | Required | Description | Example |
|---|---|---|---|
activity | No | User's state (walking, running, driving etc.) | 0 - driving (iOS automotive) |
beaconid | No | Beacon identifier | 2792c5ca-b8fa-11e2-99a7-14109fd63bf9 |
beaconidtype | No | Beacon protocol | iBeacon |
beaconproximity | No | Proximity description | near |
beaconmajor | No | Used to identify beacon | 123 |
beaconminor | No | Used to identify beacon | 456 |
beaconurl | No | Beacon url | |
bundle | No | Application bundle or package name | com.gt.mygame |
carrier | No | The name of the mobile service provider: at&t If mot in the list above, simply send the name of the carrier that the telephony API offers the application | verizon |
city | No | The city the device is located in | san diego |
connectiontype | No | Device connection type: 0 - Unknown | 2 |
coppa | No | Flag indicating if this request is subject to the COPPA regulations established by the USA FTC | 0 |
devicetype | No | Type of device: mobile/tablet | tablet |
domain | No | Application or site domain | meetme.com |
gender | No | Gender of user: m - Male | f |
ip | No | IPv4 address of the device | 127.0.0.1 |
ipv6 | No | IPv6 address of the device | 2001:cdba:0000:0000:0000:0000:3257:9652 |
language | No | Language. Default value is "en-us". Use standard values from ISO 6391 | en-us |
make | No | Make of the device | LG717 |
model | No | Model of the device | SGH-T429 |
name | No | Application or site name | mygame |
osv | No | Version of the operating system | 7 |
paid | No | 0 - Free version of application | 1 |
publisherdomain | No | Publisher domain name | groundtruth.com |
publisherid | No | Publisher id | groundtruth |
publishername | No | Publisher name | groundtruth |
region | No | Two letter state code in US | ca |
storeurl | No | Application url (URL encoded). For mobile web sites use the URL where the site resides. For native apps it will be the URL to the app store | https%3A%2F%2Fitunes.apple.com%2Fus%2Fapp%2Ffind-my-iphone%2Fid376101648 |
ua | No | User agent of the browser if applicable | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36 |
ver | No | Application or site version | 1 |
yob | No | User’s year of birth | 1980 |
zip | No | The zip code in which the device is located | 90210 |
0000000000000000000000000000000000000000000000 |
File preparation
Data must be delivered in CSV format and can be compressed. If the data is huge, you must chunk them into parts:
If transferred uncompressed, files must each be 1GB in size
If transferred compressed, files must each be 500MB in size
If the total volume of data transferred is less than this amount, must transfer a single file containing all of the data
We support both .gz and .zip compressed files.
You can also choose to break the payload into multiple files called parts. For example you can break a 400MB file into 2x 200MB files part_0001.csv and part_0002.csv.
Data Uploading
You will be provided a destination folder on our Amazon S3 bucket from which you will be able to upload your data file(s) along with a success file.
S3://dataprovidersapi/<partner_name>Upload your files in the correct subfolder structure of the following format:
/<year>/<month>/<day>/For example if today was April 12, 2018 you will need to upload your files in the following subfolder:
S3://dataprovidersapi/your-biz-name/2018/04/12Once you upload all your files you will need to make sure you also upload a success file named _SUCCESS. The contents of that file should contain the total number of rows transferred to that bucket for that day. There should only be one success file per day. The reason this is needed are:
- to know when all your files are fully uploaded and
- as a checksum to confirm the read was successful
Updated 5 days ago