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 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.

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
1 - Web / Mobile Web

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.
Used for traffic segmentation. If not able to pass individual traffic sources, static name of company passing data is required

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
Users' AAID for Android

46ab0a92-8497-46dd-b70a-d640a225ec24

uidtype

YES

pass "IDFA" for iOS
pass "AAID " for Android

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
1 - 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
1 - Tracking must be limited per commercial guidelines

0

Supported Fields

Field

Required

Description

Example

activity

No

User'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)

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

https://someurl.com

bundle

No

Application bundle or package name

com.gt.mygame

carrier

No

The 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

city

No

The city the device is located in

san diego

connectiontype

No

Device 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

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
pc
connected tv
phone
tablet
connected device
set top box

tablet

domain

No

Application or site domain

meetme.com

gender

No

Gender of user:

m - Male
f - Female
u - Unknown

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 639­1

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 - Paid 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/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

Places API