GPS Tracking

9min

Introduction
GPS tracking allows locating vehicles and assets using GPS devices and external providers services. This guide covers integrating GPS based tracking into your applications by leveraging the Motion Tracking Service (MTS) APIs and its default provider integrations. 
﻿Consent﻿
For GPS-based tracking, consent is obtained upfront from vehicle owners through paperwork during supplier onboarding.
Integration Flow
Integrating smartphone tracking with your applications involves the following steps:
Create a track: Use CreateTrack to create a new tracking request.
Start/Stop tracking: Use UpdateTrack to initiate tracking a device to obtain real-time or periodic location data, or to stop tracking a device when it is no longer needed or at the end of the consent period.
Retrieve Data: GetTraceData to retrieve the device location tracking data.
Step 1: Create a Location Track
Call CreateGPSTrack to initiate tracking for a device. The request requires the externalRefId. Note that any created tracks not started within 24 hours will be deleted. See the request body parameters below.
Parameter
Description
vehicleNumber*﻿
A unique id or the GPS device. 
externalRefId
A user-provided id that will be mapped to the trackingId. 
defaultStart
The start of the track. If the flag is passed as true, tracking will start and the API will return a 202. If it's passed as false, tracking won't start and and the response will be 201.
expiry
The track expiration. The maximum allowed time for the track to stop is 60 days if stop track API is not called. Examples: 2 hours -> 2h, 1 day -> 1d, 50 seconds -> 50s, 3 hours 4 minutes 7 seconds -> 3h4m7s.
callback
The callback details at which user will receive callback response.
callback.url*﻿
URL to receive the callback response. Must match the pattern https?://(www\.)?[-a-zA-Z0-9@:%._\+#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%_\+.#?&//=]*)
callback.meta
A meta object that will be part of the callback body. Optional and can contain user-defined data.
callback.secret
Base64 encoded HMAC secret key.
Example Request
JSON
{
  "vehicleNumber": "MH12AB2345",
  "externalRefId": "asset-truck-1",
  "defaultStart": false, 
  "expiry": "2d4h3m",
  "callback": {
    "url": "https://mycallbacks.com/gps",
    "meta": {
      "event": "start"  
    },
    "secret": "bXktc2VjcmV0LWtleQ=="
  }
}
{
  "vehicleNumber": "MH12AB2345",
  "externalRefId": "asset-truck-1",
  "defaultStart": false, 
  "expiry": "2d4h3m",
  "callback": {
    "url": "https://mycallbacks.com/gps",
    "meta": {
      "event": "start"  
    },
    "secret": "bXktc2VjcmV0LWtleQ=="
  }
}
﻿
Example Response
JSON
{
  "error": {},
  "data": {
    "trackId": "mts:track:497cff90-a8b4-e4cc-0083-b2b16071ba1a",
    "trackName": "my-new-gps-track"
  }
}
{
  "error": {},
  "data": {
    "trackId": "mts:track:497cff90-a8b4-e4cc-0083-b2b16071ba1a",
    "trackName": "my-new-gps-track"
  }
}
﻿
The response includes the data object containing the trackId and trackName.
Step 2: Start or Stop Tracking
Call UpdateGPSTrack to start or stop tracking by passing START or STOP in request body. See the request parameters below. You can start or stop a track using the trackID or trackName obtained from the CreateGPSTrack request. 
Path Parameters
Parameter
Data Type
Description
trackId* or trackName*﻿
string
The unique id for the MTS track. 
Body Parameters
Parameter
Description
operation*﻿
Example: START. Enum: [START, STOP]. The operation to perform.
callback
Object containing callback details.
callback.url*﻿
URL to receive the callback response. Must match the pattern https?://(www\.)?[-a-zA-Z0-9@:%._\+#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%_\+.#?&//=]*)
callback.meta
A meta object that will be part of the callback body. Optional and can contain user-defined data.
callback.secret
Base64 encoded HMAC secret key.
The example request below starts tracking:
JSON
{
  "operation": "START",
  "callback": {
    "url": "https://myserver.com/callbacks",
    "meta": {},
    "secret": "string"
  }
}
{
  "operation": "START",
  "callback": {
    "url": "https://myserver.com/callbacks",
    "meta": {},
    "secret": "string"
  }
}
﻿
On success, the API returns a 202 response with an id.
JSON
{
  "data": {
    "id": "mts:track:eaed3c14-b990-4f20-e911-bb31c4fde895"
  }
}
{
  "data": {
    "id": "mts:track:eaed3c14-b990-4f20-e911-bb31c4fde895"
  }
}
﻿
Step 3: Get Location Data
After the tracking has started, an application will need to call GetTraceData using the trackName or trackId to get the trace points of the device in geojson format.
Step 4: Get Tracking Status
Developers can use the following APIs to retrieve the tracking status. These APIs returns the status of tracking (started/stopped) associated with the given deviceId with details such as trackingID and the duration of tracking.
﻿GetPhoneTrackStatusByVehicleNumber﻿
﻿GetPhoneTrackStatusByName 
﻿GetPhoneTrackStatusById﻿
GetTrackingStatus
{
  "data": {
    "status": "STARTED",
    "trackId": "mts:track:62b77d4a-6487-48bd-98b9-5013d8aefcbf",
    "trackName": "my_gps_track",
    "startedAt": 1678011594259,
    "stoppedAt": 0,
    "externalRefId": "ref:0d8fef84-baac-46c9-8cf0-77c5b9abf2de",
    "app": "com.myapp",
    "totalTraces": 364,
    "routeStats": {
      "confidence": "high",
      "distance": 10450,  
      "errorReason": null    
    }
  } 
}
{
  "data": {
    "status": "STARTED",
    "trackId": "mts:track:62b77d4a-6487-48bd-98b9-5013d8aefcbf",
    "trackName": "my_gps_track",
    "startedAt": 1678011594259,
    "stoppedAt": 0,
    "externalRefId": "ref:0d8fef84-baac-46c9-8cf0-77c5b9abf2de",
    "app": "com.myapp",
    "totalTraces": 364,
    "routeStats": {
      "confidence": "high",
      "distance": 10450,  
      "errorReason": null    
    }
  } 
}
﻿
﻿

Parameter	Description
vehicleNumber*	A unique id or the GPS device.
externalRefId	A user-provided id that will be mapped to the trackingId.
defaultStart	The start of the track. If the flag is passed as true, tracking will start and the API will return a 202. If it's passed as false, tracking won't start and and the response will be 201.
expiry	The track expiration. The maximum allowed time for the track to stop is 60 days if stop track API is not called. Examples: 2 hours -> 2h, 1 day -> 1d, 50 seconds -> 50s, 3 hours 4 minutes 7 seconds -> 3h4m7s.
callback	The callback details at which user will receive callback response.
callback.url*	URL to receive the callback response. Must match the pattern https?://(www\.)?[-a-zA-Z0-9@:%._\+#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%_\+.#?&//=]*)
callback.meta	A meta object that will be part of the callback body. Optional and can contain user-defined data.
callback.secret	Base64 encoded HMAC secret key.

Parameter	Data Type	Description
trackId* or trackName*	string	The unique id for the MTS track.

Parameter	Description
operation*	Example: START. Enum: [START, STOP]. The operation to perform.
callback	Object containing callback details.
callback.url*	URL to receive the callback response. Must match the pattern https?://(www\.)?[-a-zA-Z0-9@:%._\+#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%_\+.#?&//=]*)
callback.meta	A meta object that will be part of the callback body. Optional and can contain user-defined data.
callback.secret	Base64 encoded HMAC secret key.

Updated 29 Feb 2024

Did this page help you?

SIM-Based Tracking

Smartphone Tracking