OS1 Services
...
Location Service
Location Tracking

Smartphone Tracking

9min

Introduction

Smartphone tracking enables app developers to locate devices using mobile network connectivity and signaling interfaces. It provides real-time location monitoring of smartphones. This developer guide explains how to integrate with the Motion Tracking Service (MTS) platform to add smartphone tracking capabilities to your applications.

Integration Flow

Integrating smartphone tracking with your applications involves the following steps:

  1. Create a track: Use CreateTrack to create a new tracking request.
  2. 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.
  3. Retrieve Data: GetTraceData to retrieve the device location tracking data.

Step 1: Create a Location Track

Call CreateSmartPhoneTrack 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

contextId*

A unique identifier that is used to generate trackName and trackId. If the user does not provide an externalRefId, a unique trackId will be generated and provided in response.

externalRefId

An user-provided id that will be mapped to the trackId.

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


Example Response

JSON


The response includes the data object containing the trackId and trackName.

Step 2: Start or Stop Tracking

Call UpdateSmartPhoneTrack 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


On success, the API returns a 202 response with an id.

JSON


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.



GetTrackingStatus




Updated 21 Feb 2024
Did this page help you?