GPS Tracking

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 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 contextid 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 contextid 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 { "vehiclenumber" "mh12ab2345", "contextid" "asset truck 1", "defaultstart" false, "expiry" "2d4h3m", "callback" { "url" "https //mycallbacks com/gps", "meta" { "event" "start" }, "secret" "bxktc2vjcmv0lwtleq==" } } example response { "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 { "operation" "start", "callback" { "url" "https //myserver com/callbacks", "meta" {}, "secret" "string" } } on success, the api returns a 202 response with an id { "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, "contextid" "ref 0d8fef84 baac 46c9 8cf0 77c5b9abf2de", "app" "com myapp", "totaltraces" 364, "routestats" { "confidence" "high", "distance" 10450, "errorreason" null } } }