Speed Profiling

overview motion tracking system (mts) now offers a speed profiling feature that helps classify a vehicle's speed as either halted , normal , or overspeeding this categorization is done based on the provided speed configuration developers can identify instances of over speeding and halting of their vehicle by utilizing this feature in their applications the speed profiling feature supports push and pull based methods to get the speed profile developers can either use the pull based get speed profiling or push based realtime speed profiling events as per their preference both methods are described in detailed manner in the following sections pull based get speed profiling setting the speed profile parameter to true in the gettrace api initiates the get speed profiling feature traces are fetched from the database based on the provided parameters like limit , start , duration , and nextpage the fetched traces are stored in a cache for quick retrieval during subsequent requests subsets of traces are formed by combining the traces to be returned in the current page with the traces from the previous page the average speed over these trace subsets is calculated and compared with the overspeed and halt thresholds each trace point is assigned a profile of either "normal", "halted", or "overspeeding" based on the speed comparison the gettrace response returns the traces along with their speed profiles in a paginated manner, meaning the results are divided into multiple pages apis to get speed profile developers can use the following query parameters with the gettrace api to fetch speed profiling data for a specific device using the trackname https //docs getos1 com/reference/get trace data using trackname or trackid https //docs getos1 com/reference/get trace data using trackid parameter description start the timestamp, represented in milliseconds, from which the traces should be retrieved duration the time for which data packets need to be fetched limit the number of items to return speed profile set to true to perform speed profiling tracecount groups a specific number of traces to calculate the vehicle's average speed speed profiling will start at (tracecount 1)nth index on the first page overspeed the speed threshold in meters/seconds above which a vehicle will be classified as "overspeeding" halt the speed threshold in meters/seconds below which a vehicle will be classified as "halted" request the following gettrace request retrieves a full trace for the specified trackname labeled “example track” the request includes the following query parameters to track the speed profiling start in this request, the value is set to 1626413830000 to retrieve traces starting from that specific timestamp duration specifies the duration for which the trace data should be retrieved in this example the value is set to 1h to retrieve traces for a duration of 1 hour from the specified start timestamp limit specifies the maximum number of trace points to be returned in the response in the example the value is set to 100, limiting the response to a maximum of 100 trace points speed profile enables or disables the speed profiling feature this example sets the value to true to enable speed profiling for the retrieved traces halt specifies the speed threshold below which a trace point will be classified as "halted" the example sets the value to 10, meaning that any trace point with a speed below 10 units will be considered as "halted" overspeed specifies the speed threshold above which a trace point will be classified as "overspeeding" this example sets the value to 80, meaning that any trace point with a speed above 80 units will be considered as "overspeeding" tracecount specifies the number of trace points that should be grouped together to calculate the average speed of the vehicle this example sets the value to 10, meaning that the average speed should be calculated using groups of 10 trace points it's important to note that speed profiling will be provided starting from the (tracecount 1) index on the first page of the response this means that if tracecount is set to 10, speed profiling will start from the 9th index (0 based) on the first page speed profiling for sim based tracking speed profiling for sim based tracking we recommend using speed profiling feature only for gps or smartphone based trace data we do not recommend usage of speed profiling feature for sim based data because the sim based tracking data is relatively less accurate and is shared with a lower frequency (15 mins or higher) curl x get \\ 'https //example api comm/mts/track/example track/traces?start=1626413830000\&duration=1h\&limit=100\&speed profile=true\&halt=10\&overspeed=80\&tracecount=10' \\ h 'accept application/json' response { "request" { "body" {}, "querystring" "start=1626413830000\&duration=1h\&limit=100\&speed profile=true\&halt=10\&overspeed=80\&tracecount=10", "uri" "https //example api com/mts/track/example track/traces" }, "error" { "additionalinfo" {}, "code" 0, "description" "ok" }, "data" \[ { "app" "example app", "deviceid" "8a7b6c5d 4e3f 2g1h 0i9j 8k7l6m5n4o3p", "lat" 37 7749, "lon" 122 4194, "mtsarrivaltis" 1626413830000, "tis" 1626413830000, "accuracy" 10, "provider" "gps", "speed" 5, "seq" 1, "event" { "name" "start", "data" {} }, "trackid" "5f4e0d82 9c5a 4b4f 9b2c 5d4c3b2a1c0d", "trackname" "example track", "speedprofile" "halt", "distance" 0 }, { "app" "example app", "deviceid" "2b1c3d4e 5f6a 7b8c 9d0e 1a2b3c4d5e6f", "lat" 37 7850, "lon" 122 4290, "mtsarrivaltis" 1626413840000, "tis" 1626413840000, "accuracy" 12, "provider" "gps", "speed" 90, "seq" 2, "event" { "name" "update", "data" {} }, "trackid" "5f4e0d82 9c5a 4b4f 9b2c 5d4c3b2a1c0d", "trackname" "example track", "speedprofile" "overspeed", "distance" 1000 }, { "app" "example app", "deviceid" "9c8d7e6f 5a4b 3c2d 1e0f 9g8h7i6j5k4l", "lat" 37 7900, "lon" 122 4350, "mtsarrivaltis" 1626413850000, "tis" 1626413850000, "accuracy" 15, "provider" "gps", "speed" 40, "seq" 3, "event" { "name" "update", "data" {} }, "trackid" "example track", "trackname" "example track", "speedprofile" "normal", "distance" 1500 } ], "meta" { "hasnextpage" true, "nextpage" "https //example api com/mts/track/example track/traces?start=1626413850000\&duration=1h\&limit=100\&speed profile=true\&halt=10\&overspeed=80\&tracecount=10" } } the example response includes an array containing three trace objects each trace object has different speed values to demonstrate different speed profiles based on the defined parameters in the request ( halt=10 , overspeed=80 , tracecount=10 ) here's a breakdown of the speed profiles for each trace object the first trace object has a speed of 5, which is considered a "halt" because it is below the halt threshold of 10 the second trace object has a speed of 90, which is considered an "overspeed" because it exceeds the overspeed threshold of 80 the third trace object has a speed of 40, which is considered "normal" because it falls within the normal range between the halt and overspeed thresholds push based real time speed profiling in addition to the ability to get a speed profile, mts provides real time speed profiling events this can be used to notify fleet/dispatch managers whenever a vehicle or ground resource is over speeding or halting register an event subscription to subscribe a device for event notifications, you can use the registereventsubscriptions api this api enables you to receive alerts for speed profiling and trace data at a specific callback url for a duration of 30 minutes however, it's important to note that you cannot modify existing events to include speed profiling if you want to include speed profiling, you will need to register a new event subscription path parameters parameter description trackid the id of the track for which profiling events are required body parameters parameter description callback the callback details for receiving profiling event notifications duration the duration (in seconds) over which the speed should be averaged for profiling halt the speed threshold below which a trace point will be classified as "halted" overspeed the speed threshold above which a trace point will be classified as "over speeding" meta additional metadata to include example request this example demonstrates how a developer can register an event subscription for a specific track, providing the necessary callback details, speed profiling parameters, and enabling speed profile notifications { "callback" { "url" "https //example com/callback", "meta" {}, "secret" "c2vjcmv0s2v5" }, "externalrefid" "subscription123", "tracecount" 5, "halt" 20, "overspeed" 100, "enablespeedprofile" true } example response the response indicates that the event subscription was successfully registered it includes the unique id of the created subscription the externalrefid for reference { "data" { "id" "a1b2c3d4 e5f6 7g8h 9i0j 1k2l3m4n5o6p", "externalrefid" "subscription123" } } receiving profiling event notifications when a profiling event occurs (i e , when a vehicle moves from one speed profile to another), a callback notification will be sent to the specified callback url in the registereventsubscription request the notification will include the following details timestamp the timestamp at which the profile change occurred deviceid the id of the device associated with the profile change trackid the id of the track associated with the profile change lat the latitude coordinate of the device at the time of the profile change lon the longitude coordinate of the device at the time of the profile change app the application associated with the device previous speed profile the speed profile of the device before the change current speed profile the new speed profile of the device after the change meta additional metadata provided during the subscription retrieve event subscriptions developers can use the following endpoints to retrieve event subscriptions listeventsubscriptions lists all event subscription geteventsubscription get a specific event subscription by external ref id unsubscribe to event subscriptions developers can call deleteeventsubscription to unsubscribe event subscriptions