SIM-Based Tracking

14min

Introduction
SIM-based tracking enables app developers to locate mobile devices using a driver's cellular network. Using the location coordinates recorded by the driver’s cellular network, you can locate and monitor your fleet’s activities without the use of traditional GPS trackers. SIM Based Tracking works for both feature phones and smartphones It provides real-time location monitoring of the devices. This developer guide explains how to integrate with the Motion Tracking Service (MTS) platform to add SIM-based tracking capabilities to your applications. 
The integration is built around the following key features:
Consent Management: To track your ground resources you need to first get consent from the driver being tracked. Using our Consent APIs apps can initiate a consent to track and check its status. Consent is shared to the driver using an SMS message to which they can reply and provide consent to track.
Location Tracking: Once you have retrieved consent from the driver you can create the track and receive traces for that device in real time.
Integration Flow
Integrating sim-based tracking with your applications involves the following steps:
Initiate Consent: Use RequestConsent API to obtain consent for SIM-based tracking.
Device Location Tracking: Manage tracking requests and retrieve location data.
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: Initiate Consent
For Request consent for a phoneNumber by calling RequestConsent. View the request parameters below:
Path Parameters
Parameter
Data Type
Description
msisdn
string
We'll accept phone number in msisdn format. This regex will be used to validate it - ^\\d{1,12}$
Body Parameters
Parameter
Data Type
Description
callback
Callback3P
Callback details at which user will receive callback response.
callback.url*﻿
string (pattern)
URL
callback.meta
object
Developers can add a meta object that will be a part of the callback body.
callback.secret
string
base64 encoded hmac secret key.
Refer to the example below for requesting consent:
JSON
{
  "callback": {
    "url": "https://myserver.com/callbacks",
    "meta": {},
    "secret": "MWYyZDFlMmU2N2Rm"
  }
}
{
  "callback": {
    "url": "https://myserver.com/callbacks",
    "meta": {},
    "secret": "MWYyZDFlMmU2N2Rm"
  }
}
﻿
The response includes the status of the consent request.
JSON
{
  "data": {
    "status": "INITIATED"
  },
  "error": {}
}
{
  "data": {
    "status": "INITIATED"
  },
  "error": {}
}
﻿
Step 2: Retrieve Consent
After initiating consent, call RetrieveConsent to fetch the consent status. This returns the consentStatus, and the time the consent was requested and received.
JSON
{
  "data": {
    "consentStatus": "ALLOWED",
    "expiryAt": 1699873625645,
    "consentRequestedAt": 0,
    "consentReceivedAt": 0
  }
}
{
  "data": {
    "consentStatus": "ALLOWED",
    "expiryAt": 1699873625645,
    "consentRequestedAt": 0,
    "consentReceivedAt": 0
  }
}
﻿
Step 3: Create a Location Track
Call CreateSimTrack to initiate tracking for a device. The request requires the msisdn. Note that any created tracks not started within 24 hours will be deleted. See the request body parameters below.
Parameter
Description
msisdn*﻿
The msisdn using the phoneNumber format "9198********"
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
{
  "msisdn": "919876543210",
  "defaultStart": false,
  "expiry": "14d",
  "callback": {
    "url": "https://example.com/sim-tracking-callbacks", 
    "meta": {},
    "secret": "c2VjcmV0" 
  }
}
{
  "msisdn": "919876543210",
  "defaultStart": false,
  "expiry": "14d",
  "callback": {
    "url": "https://example.com/sim-tracking-callbacks", 
    "meta": {},
    "secret": "c2VjcmV0" 
  }
}
﻿
Example Response
JSON
{
  "error": {},
  "data": {
    "trackId": "mts:track:497cff90-a8b4-e4cc-0083-b2b16071ba1a",
    "trackName": "my-new-sim-track"
  }
}
{
  "error": {},
  "data": {
    "trackId": "mts:track:497cff90-a8b4-e4cc-0083-b2b16071ba1a",
    "trackName": "my-new-sim-track"
  }
}
﻿
The response includes the data object containing the trackId and trackName.
Step 4: Start or Stop Tracking
Call UpdateSimTrack 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. 
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 5: Get Location Data
﻿﻿Consent ﻿Status﻿﻿
Once you have initiated the tracking process, if you notice that the trace data has unexpectedly stopped without you stopping it, this could be because the user revoked their consent while the tracking was in progress. In such situations, developers need to call GetConsentStatus to verify the existence of a valid consent.
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 6: 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.
﻿GetSimTrackStatusByMsisdn﻿
﻿GetSimTrackStatusByName 
﻿GetSimTrackStatusById﻿
﻿
GetTrackingStatus
{
  "data": {
    "status": "INITIATED",
    "trackId": "track12345",
    "externalRefId": "ref:93586cb3-3388-4abe-ac2b-60db3280a4d6",
    "deviceId": "device98765",
    "consentStatus": "GRANTED",
    "startedAt": 1633036800, 
    "stoppedAt": 1633040400,
    "rsOutput": {
      "confidence": "HIGH",
      "distance": 500,  
      "errorReason": [
        "LowSignalStrength"
      ]
    }
  }
}
{
  "data": {
    "status": "INITIATED",
    "trackId": "track12345",
    "externalRefId": "ref:93586cb3-3388-4abe-ac2b-60db3280a4d6",
    "deviceId": "device98765",
    "consentStatus": "GRANTED",
    "startedAt": 1633036800, 
    "stoppedAt": 1633040400,
    "rsOutput": {
      "confidence": "HIGH",
      "distance": 500,  
      "errorReason": [
        "LowSignalStrength"
      ]
    }
  }
}
﻿
﻿

Parameter	Data Type	Description
msisdn	string	We'll accept phone number in msisdn format. This regex will be used to validate it - ^\\d{1,12}$

Parameter	Data Type	Description
callback	Callback3P	Callback details at which user will receive callback response.
callback.url*	string (pattern)	URL
callback.meta	object	Developers can add a meta object that will be a part of the callback body.
callback.secret	string	base64 encoded hmac secret key.

Parameter	Description
msisdn*	The msisdn using the phoneNumber format "9198********"
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 07 May 2024

Did this page help you?

Location Tracking

GPS Tracking