Back to LiveTrack24 API Home

LiveTrack24 LiveTracking API v2

Introduction

The new LiveTrack24 LiveTracking API:

• supports multiple data formats,
• is more secure, more robust and fail safe,
• handles better mobile signal loss and other anomalies,
• it is friendlier to the developer.

Tracking API v2 URL call HTTP GET and POST requests

Formats

URL parts

http://[server].livetrack24.com/api/[dataFormat]/lt/[OpCode]/[AppKey]

/[AppVersion]/[SessionID]/[UserID]/[PasswordToken]/[OpCodeParameters]

/[OptionalParameters]

GET & POST

http://[server].livetrack24.com/api/[dataFormat]/lt?op=[OpCode]&ak=[AppKey]

&vr=[AppVersion]&sid=[SessionID]&uid=[UserID]&pt=[PasswordToken]

{[OpCodeParameters]}{[OptionalParameters]}

Server response format

<code>;<message>
[<content in multiple lines>]

On success

code                is 0

message        is OK

content        the rest of the reply if needed.

Example response on success:

0;OK

11401

where 0;OK means no error and at the next line 11401 is the returned user id.

On error

code                is not 0

message        is the error message

content        is extra information about the error to help the developer.

Example response on error:

20;Unknown user

where 20 is the error code and the ; separates it from the error message.

Common URL Parts - Detailed Descriptions

5. /[DataFormat]

t        'text'                plain text values, single or multiple values with no compression or delta

d        'delta'                Delta, RLE, GBase64 packed (see below)

z        'compressed'        Can be used with delta to further compress  [NOT YET IMPLEMENTED]

b        'binary'                BIT STREAM highly compressed [NOT YET IMPLEMENTED]

Example:

http://t2.livetrack24.com/api/t/...

where t means plain text values

13. /[PasswordToken]

A unique per session (track) password token. That is a URL safe base64 string based on the SessionID (it can be 0 for some op codes), the user password and your AppSecret (obtained from LiveTrack24, unique per App).

PasswordToken calculation in PHP:

$lowerPassMD5 = md5(strtolower($plainTextPassword));                 // hex MD5

$tokenString = md5($lowerPassMD5 . $sessionID );                     // hex MD5

$tokenString = $tokenString . $lowerPassMD5 . $appSecret;

$base64Token = base64_encode(md5($tokenString, true));            // binary MD5!!!

$passwordToken = strtr($base64Token, '+/=', '-_,');                // URL safe

$passwordToken = rtrim($passwordToken, ',');                          // beautify

quick check

PasswordToken maker - Working sample in PHP for quick testing and verification.

demo input

$plainTextPassword = 'thisIsMyPass';

$appSecret = 'This-Is-An-App-Secret';

$sessionID = 605419896;

demo output

xjFqBpRZR2trZltB5C2pRg

Example: (the URL below is split in 2 rows for easier reading)

http://t2.livetrack24.com/api/t/lt/trackEnd/WhudO/1.0.3/unique_device_id

/605419896/11401/xjFqBpRZR2trZltB5C2pRg/...

where xjFqBpRZR2trZltB5C2pRg is the password token for user with ID 11401 and this track with SessionID 605419896.

Op code specific parameters

7. /getUserID

Op code getUserID is used to get the user id for a user.

/[Username]

Example:  (the URL below is split in 2 rows for easier reading)

http://t2.livetrack24.com/api/t/lt/getUserID/WhudO/1.0.3/unique_device_id

/0/0/xjFqBpRZR2trZltB5C2pRg/testUser

where /0/0 is used instead of sessionID and userID and testUser is the username we want the user id for.

Example response on success:

0;OK

11401

where 0;OK means no error and at the next line 11401 is the returned user id.

Example response on error:

20;Unknown user

where 20 is the error code and the ; separates it from the error message.

Password Notice: The user may change his/her password on the server at anytime, to ensure an App has the correct password, the App has to verify it periodically by calling getUserID and / or by checking the response of any other call for error: 22;Wrong password

Important: Because getUserID is used to detect the correctness of the credentials and possible password change, should be called:

• the time the credentials are entered by the user,
• every time your app starts,
• once just before a live tracking session.

A brief explanation about LiveTracking Profiles

Users can have multiple tracking profiles with activity, equipment, alerts, submission and privacy settings stored in the server. Any of these will have ProfileID from 1 to 98 and can be used by you, the app.

3 Mar 2014 Update: There is also a special app defined user profile with ProfileID 99 which is handled by you and can be updated to the server. This profile is not listed server side. Kind of:

"select one of your predefined profiles:

1. Public Paraglider ← profile names

2. Public Running

or use these settings:

privacy: [Private] ← selectable

equipment type: [Car]  ← selectable

equipment name: [TUCSON] ← writable or selectable

"

7. /updateProfile

Op code updateProfile is used to update the app defined user profile 99 to the server. It should be called when the profile 99 settings are changed in the app and when starting a new track which uses the profile 99 and.

/[Privacy]/[TrackCategory]/[EquipmentName]/[DeviceModel]

Example:  (the URL below is split in 3 rows for easier reading)

http://t2.livetrack24.com/api/t/lt/updateProfile/WhudO/1.0.3/unique_device_id

/0/11401/Yu6a78WAjCl8GL-e2MWRgg

/0/16/Gradient Avax%20SR23/Lenovo%20P780

where the 0 in the 3rd row means visible to all (public) and the 16 is the vehicle type for paramotor.

Privacy Notice: Changing the privacy settings during a LiveTracking session will result to unspecified behavior and thus it should not be implemented by the App.

7. /getProfiles

Op code getProfiles is used to get the list of the user’s profile ids and names separated by newline (\n) char. It is recommended to check the existence of the selected profile with this before starting a new track. Profile 99 is not returned here.

Example:  (the URL below is split in 2 rows for easier reading)

http://t2.livetrack24.com/api/t/lt/getProfiles/WhudO/1.0.3/unique_device_id

/0/11401/Yu6a78WAjCl8GL-e2MWRgg

Example response on success with profiles:

0;OK

1;Public Paragliding

2;Private Paragliding

5;Public Running

7;Private Running

19;Car

45;Testing

where 0;OK means no error and at the next lines contain the user profiles.

response on success without profiles:

0;OK

where 0;OK means no error but there are no profile results because the user does not have any.

LiveTracking op codes  ‘track’ and ‘trackEnd’

Common URL Parts

14/15. /[Privacy]/[ProfileID] - Combinations

Privacy Notices: 

• Any other Privacy/ProfileID combination raises an error and the GPS packet is ignored.
• Changing the privacy settings during a LiveTracking session will result to unspecified behavior and thus it should not be implemented by the App.

7. /track

Op code track is used to send GPS point(s).

/[TimeList]/[LatList]/[LonList]/[AltList]/[SOGlist]/[COGlist](/[TrackInfo])?

The URL parts 17-22 here can be single values or comma separated lists of values. All the lists of a call should have the same number of values.

23. /[TrackInfo]

This applies to the 1st packet of the track ( PacketID = 1 ).  Depending on the ProfileID we send the following “:” separated URL encoded information:

IF ProfileID = 99 THEN

[TrackCategory]:[EquipmentName]:[DeviceModel]

ELSE

[DeviceModel]

TrackInfo encoding in PHP:

$TrackInfo = $TrackCategory                // this is an integer no encoding
. ":" . urlencode($EquipmentName)        // URL encoded string
. ":" . urlencode($DeviceModel);        // URL encoded string

Examples:  (the URLs below are split in 4 rows for easier reading)

http://t2.livetrack24.com/api/t/lt/track/WhudO/1.0.3/unique_device_id

/605419896/11401/xjFqBpRZR2trZltB5C2pRg

/0/99/1/1387259187/40.62302/22.96950/89/34/145

/16:Gradient%20Avax%20SR23:Lenovo%20P780

in the above, PacketID = 1, ProfileID = 99, we send complete track info.

http://t2.livetrack24.com/api/t/lt/track/WhudO/1.0.3/unique_device_id

/605419896/11401/xjFqBpRZR2trZltB5C2pRg

/9/2/1/1387259187/40.62302/22.96950/89/34/145

/Lenovo%20P780

above, PacketID = 1, ProfileID != 99, we send the device model only.

http://t2.livetrack24.com/api/t/lt/track/WhudO/1.0.3/unique_device_id

/605419896/11401/xjFqBpRZR2trZltB5C2pRg

/0/99/2/1387259187/40.62302/22.96950/89/34/145

above, PacketID > 1, we send no track info.

Example response on success:

0;OK

where 0;OK means no error.

7. /trackEnd

Op code trackEnd is used to send the end of a track reporting the status of the user.

/[ProblemID]/[Submit]

Example:  (the URL below is split in 3 rows for easier reading)

http://t2.livetrack24.com/api/t/lt/trackEnd/WhudO/1.0.3/unique_device_id

/605419896/11401/xjFqBpRZR2trZltB5C2pRg/3

/0/99/2156/0/1

Complete Live Tracking Example - Simple scenario

App details

Let’s assume the App has the following details:

appKey = WhudO

appSecret = This-Is-An-App-Secret

appVersion = 1.0.3

and runs on a device with id: unique_device_id

Get username, password and userID

The App asks the user within a login page for:

1. Username in LiveTrack24 (let’s say the user types: testUser)
2. and password (let’s say the user types: thisIsMyPass)

when the user clicks Login the App calculates the password token with:

sessionID = 0

plainTextPassword = thisIsMyPass

appSecret = This-Is-An-App-Secret

let’s assume the result is: A-Password-Token

the userID is still unknown, so we use userID = 0  

The App gets the userID by calling:

http://t2.livetrack24.com/api/t/lt/getUserID/WhudO/1.0.3/unique_device_id/0/0/A-Password-Token/testUser

The reply on error may be:

22;Wrong password

The App should ask the user for the correct username and password.

The reply on success will be:

0;OK

11401

where 11401 is the userID, the App stores that.

Get profile details, update profile

The App asks the user within a settings page for:

1. TrackCategory (let’s say the user selects “Paramotor” that has category ID 16)
2. EquipmentName (let’s say the user types Gradient Avax SR23)
3. Privacy (let’s say the user select “Public” that is 0)

and gets the phone model DeviceModel for the system, let’s say it is a Lenovo P780)

When the user click OK the App updates the app profile on the server by calling:

http://t2.livetrack24.com/api/t/lt/updateProfile/WhudO/1.0.3/unique_device_id/0/11401
/A-Password-Token/0/16/Gradient Avax SR23/Lenovo P780

A LiveTracking session

The user selects Start LiveTracking.

The App generates a new random 32 bit unsigned integer for sessionID, let’s say 605419896 and calculates the sessioned password token for our example with:

sessionID = 605419896

plainTextPassword = thisIsMyPass

appSecret = This-Is-An-App-Secret

let’s assume the result now is: This-Is-A-Password-Token

// The App can send a single GPS Point ( in the 1st packet we append the track info )

http://t2.livetrack24.com/api/t/lt/track/WhudO/1.0.3/unique_device_id/605419896/11401
/This-Is-A-Password-Token/0/99/1/1387259187/40.62302/22.96950/89/34/145
/16:Gradient%20Avax%20SR23:Lenovo%20P780

// Or several GPS Points together, here are 4

http://t2.livetrack24.com/api/t/lt/track/WhudO/1.0.3/unique_device_id/605419896/11401
/This-Is-A-Password-Token/0/99/2/1387259189,1387259191,1387259193,1387259195
/40.62301,40.62303,40.62300,40.62297/22.96949,22.96950,22.96948,22.96949/91,90,92,90
/38,37,36,35/147,150,149,151

The App is sending points until the the user selects Stop LiveTracking, then it asks the user if everything is OK and reports to the server, e.g.:

// END OF TRACK, reporting “Everything OK” and Submit

http://t2.livetrack24.com/api/t/lt/trackEnd/WhudO/1.0.3/unique_device_id/605419896/11401
/This-Is-A-Password-Token/0/99/3/0/1

Other Data Formats

5. /[DataFormat] ‘delta’

This is a Delta, RLE, GBase64 packed URL friendly text format:

Lats and Lons are converted to integer degrees (see below),

parts 17-22 of /track are packed GBase64 integers,

only the differences to the previous values are sent (delta),

RLE ‘compressed’ by default.

Convert Lat / Lon coordinates to integer degrees

In JavaScript: coordInt = ~~( coord * 60000 );

In PHP: coordInt = intval( coord * 60000 );

Sending 32 GPS Points can look like that:

http://t2.livetrack24.com/api/d/lt/track/WhudO/1.0.3/unique_device_id/605419896/11401
/xjFqBpRZR2trZltB5C2pRg/0/99/426/1iKrdi$u3/one0d!C!1d*4!C*n/c]uJa:1v!1v*4:C*j!j*3
/pw_21*o!1*3/4!3*t/0*u

An idea of how it is done

1iKrdi$u3 equals:

1387901778,1387901781,1387901784,1387901787,1387901790,1387901793,1387901796,
1387901799,1387901802,1387901805,1387901808,1387901811,1387901814,1387901817,
1387901820,1387901823,1387901826,1387901829,1387901832,1387901835,1387901838,
1387901841,1387901844,1387901847,1387901850,1387901853,1387901856,1387901859,
1387901862,1387901865,1387901868

It’s ‘delta’ equals:

1387901778:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3:3

It’s RLE equals:

1387901778$31:3

In GBase64 becomes:

1iKrdi$u3

For a working example of int GBase64 and deltaRLE library in JavaScript see:

intGBase64andDeltaRLE.html