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]
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.
Before integration, please communicate to our account manager / business development team member with an estimate number of rows per day to assess feasibility.
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.
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.
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).
The exptimestamp of each record (row) must be within 48 hours of the time of upload.
Limited Country Support
We only support the following countries: US, GB, DE, JP, CA and AU. If you have additional data please inform us so we can explicitly enabled them.
Note: The country field is depricated. Country is derived using the coordinates.
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.
Each file at a minimum must contain the following fields (can accept additional fields):
0 - Applications
Due to exclusive interest in mobile applications, the field should only be populated with 0s
UNIX timestamp of record
The bundle/name of the source providing the record.
Operating system of the device: android ios If not in the list above, provide the name of the OS that the runtime environment provides
User's IDFA for iOS
pass "IDFA" for iOS
Horizontal accuracy as it is read from the device GPS in meters. Convert to meters when device provides a different unit
Vertical accuracy as it is read from the device GPS in meters
Speed of device in MPH
Yes (Android only)
Speed Accuracy (meters per second)
An azimuth that is measured in degrees relative to north (course / bearing)
Yes (Android only)
Estimated bearing accuracy of this location (degrees)
Yes (iOS only)
Floor in building device is located
(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
0 - Not restricted by GDPR
If user is located in EU/EEA then this field must be set to 1
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.
“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where:
0 - Tracking is unrestricted
User's state (walking, running, driving etc.)
0 - driving (iOS automotive)
Used to identify beacon
Used to identify beacon
Application bundle or package name
The name of the mobile service provider:
If mot in the list above, simply send the name of the carrier that the telephony API offers the application
The city the device is located in
Device connection type:
0 - Unknown
Flag indicating if this request is subject to the COPPA regulations established by the USA FTC
Type of device:
Application or site domain
Gender of user:
m - Male
IPv4 address of the device
IPv6 address of the device
Language. Default value is "en-us". Use standard values from ISO 6391
Make of the device
Model of the device
Application or site name
Version of the operating system
0 - Free version of application
Publisher domain name
Two letter state code in US
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
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
Application or site version
User’s year of birth
The zip code in which the device is located
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.
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.
Upload your files in the correct subfolder structure of the following format:
For example if today was April 12, 2018 you will need to upload your files in the following subfolder:
Once 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 about 2 years ago