Speed Profiling
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.
- 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.
Developers can use the following query parameters with the GetTrace API to fetch speed profiling data for a specific device using the trackName or 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". |
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
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).
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.
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.
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.
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.
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.
Developers can use the following endpoints to retrieve event subscriptions:
Developers can call DeleteEventSubscription to unsubscribe event subscriptions.