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):

FieldRequiredDescriptionExample
recordtypeYES0 - Applications
1 - Web / Mobile Web

Due to exclusive interest in mobile applications, the field should only be populated with 0s
0
exptimestampYESUNIX timestamp of record1467843086186
idYESThe bundle/name of the source providing the record.
Used for traffic segmentation. If not able to pass individual traffic sources, static name of company passing data is required
com.appname
osYESOperating system of the device: android ios If not in the list above, provide the name of the OS that the runtime environment providesios
uidYESUser's IDFA for iOS
Users' AAID for Android
46ab0a92-8497-46dd-b70a-d640a225ec24
uidtypeYESpass "IDFA" for iOS
pass "AAID " for Android
IDFA
latYESUser's latitude37.79867
lonYESUser's longitude-122.41762
haYESHorizontal accuracy as it is read from the device GPS in meters​. Convert to meters when device provides a different unit10
vaYESVertical accuracy as it is read from the device GPS in meters10
altYESDevice altitude200.9
speedYESSpeed of device in MPH10
speedaccuracyYes (Android only)Speed Accuracy (meters per second)1
directionYESAn azimuth that is measured in degrees relative to north (course / bearing)90
directionaccuracyYes (Android only)Estimated bearing accuracy of this location (degrees)10
floorYes (iOS only)Floor in building device is located12
countryYES(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
gdprYES0 - Not restricted by GDPR
1 - Restricted by GDPR

If user is located in EU/EEA then this field must be set to 1
0
gpdr_consentYESThis 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=
lmtYES“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where:

0 - Tracking is unrestricted
1 - Tracking must be limited per commercial guidelines
0

Supported Fields

FieldRequiredDescriptionExample
activityNoUser's state (walking, running, driving etc.)0 - driving (iOS automotive)
1 - cycling (iOS cycling)
2 - on foot (Android only)
3 - still (iOS - stationary)
4 - unknown (iOS unknown)
5 - tilting (Android only)
7 - walking (iOS - walking)
8 - running (iOS - running)
beaconidNoBeacon identifier2792c5ca-­b8fa-­11e2-­99a7-­14109fd63bf9
beaconidtypeNoBeacon protocoliBeacon
beaconproximityNoProximity descriptionnear
beaconmajorNoUsed to identify beacon123
beaconminorNoUsed to identify beacon456
beaconurlNoBeacon urlhttps://someurl.com
bundleNoApplication bundle or package namecom.gt.mygame
carrierNoThe name of the mobile service provider:

at&t
metropcs
sprint
tmobile
verizon

If mot in the list above, simply send the name of the carrier that the telephony API offers the application
verizon
cityNoThe city the device is located insan diego
connectiontypeNoDevice connection type:

0 - Unknown
1 - Ethernet
2 - WIFI
3 - Cellular Network- Unknown Generation
4 - Cellular Network-2G
5 - Cellular Network-3G
6 - Cellular Network-4G
2
coppaNoFlag indicating if this request is subject to the COPPA regulations established by the USA FTC0
devicetypeNoType of device:

mobile/tablet
pc
connected tv
phone
tablet
connected device
set top box
tablet
domainNoApplication or site domainmeetme.com
genderNoGender of user:

m - Male
f - Female
u - Unknown
f
ipNoIPv4 address of the device127.0.0.1
ipv6NoIPv6 address of the device2001:cdba:0000:0000:0000:0000:3257:9652
languageNoLanguage. Default value is "en-­us". Use standard values from ISO 639­1en-­us
makeNoMake of the deviceLG717
modelNoModel of the deviceSGH-T429
nameNoApplication or site namemygame
osvNoVersion of the operating system7
paidNo0 - Free version of application
1 - Paid version of application
1
publisherdomainNoPublisher domain namegroundtruth.com
publisheridNoPublisher idgroundtruth
publishernameNoPublisher namegroundtruth
regionNoTwo letter state code in USca
storeurlNoApplication 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 storehttps%3A%2F%2Fitunes.apple.com%2Fus%2Fapp%2Ffind-my-iphone%2Fid376101648
uaNoUser agent of the browser if applicableMozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36
verNoApplication or site version1
yobNoUser’s year of birth1980
zipNoThe zip code in which the device is located90210
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/12

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