Speed violation alerts

Product Used: Live Tracking API

NextBillion.ai’s Live Tracking API allows users to monitor their fleet vehicles in real-time and receive alerts when the desired vehicles violate the desired speeds. Users can set up custom speed limits or use the limits specified by the local authorities. When the vehicle breaks the specified speed limit, the Live Tracking service will generate an event with detailed information about the violation and send it as an alert on any desired system(s).

Setup

Let’s go through the following steps to set-up a real-time speed alert system.

Step 1: Create Asset

First we will create an asset (vehicle) whose activity we want to track. To create an asset, we will:

• Give a meaningful “name” to the asset.
• Add the “attributes” of the asset that will be used to associate the asset to a monitor.

Following is a configured Create Asset JSON:

1curl --location 'https://api.nextbillion.io/skynet/asset?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{
4            "name": "Staff Transportation",
5            "description": "Live Tracking Speeding Event Example",
6            "attributes": {
7                "driver_contact_no": "321-902-838",
8                "driver_name": "James Smith",
9                "license": "4 ES 7167",
10                "vehicle_type": "Delivery"
11            }
12}'

As soon as the asset is created, we get the asset ID in the acknowledgement response. Please record this ID. For our example, the asset ID is:

1{
2  "status": "Ok",
3  "data": {
4    "id": "683a3672-8eb3-4ec2-a1b9-1bdc2743d491"
5  }
6}

Step 2: Bind a device to the Asset

Next step is to bind a GPS device to the asset which can upload the location and other information for the “asset” as it moves. We provide a “device_id” for the asset_id received in the previous step.

1curl --location 'https://api.nextbillion.io/skynet/asset/683a3672-8eb3-4ec2-a1b9-1bdc2743d491/bind?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{
4    "device_id":"GAW-A1-FB-JT0312"
5}'

As soon as the binding process is successful, we get an acknowledgement response from the API. Next we will define the speeding configurations which will be used for triggering alerts.

Step 3: Define Speed Configurations

Live Tracking API gives users the flexibility to set their own criteria of determining speeding states. Speeding is a state that an asset exhibits when it maintains a speed higher than a specified threshold for a duration higher than a given value. The API uses the GPS information received to calculate the speed and duration values.

Live Tracking uses following three attributes to capture speeding constraints:

1. time_tolerance: The amount of time for which an asset needs to over-speed to trigger a speed alert.
2. customer_speed_limit: The desired speed limit that should not be breached.
3. use_admin_speed_limit: This flag is used to indicate if administrative speed limits or user provided speed limits should be used for monitoring.

Following is the speeding_config object that we use:

1"speeding_config":{
2    "time_tolerance": 35000,
3    "customer_speed_limit":18,
4    "use_admin_speed_limit": false
5}

The above configuration will create speed alerts when the asset has been traveling at more than 18 m/s for more than 35 seconds. Next we will create a monitor and attach the asset to it.

Step 4: Create a Monitor

Now that we have an asset and the speeding configurations, let’s set up a monitoring criteria using a monitor. To create a monitor, we need to:

• Specify the “type” of activity that we want to track. We set this value to “speeding”.
• Specify the “speeding_config” attributes to model the configurations decided in the Step 3 above.
• Add the same “attributes” for the monitor as that of the asset to ensure that the asset is successfully linked with the monitor.

Below is the JSON we built for creating the monitor:

1curl --location 'https://api.nextbillion.io/skynet/monitor?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{
4  "type": "speeding",
5  "speeding_config": {
6    "time_tolerance": 35000,
7    "customer_speed_limit": 18,
8    "use_admin_speed_limit": false
9  },
10  "name": "Delivery Monitor The Ritz Hotel, Los Angeles",
11  "description": "Track speeding activity of the delivery vehicle",
12  "match_filter": {
13    "include_all_of_attributes": {
14      "driver_contact_no": "321-902-838",
15      "driver_name": "James Smith",
16      "license": "4 ES 7167",
17      "vehicle_type": "Delivery"
18    }

Please record the monitor ID from the API response:

1{
2  "status": "Ok",
3  "data": {
4    "id": "36c171d5-bdf1-47c2-9531-4c02820ab70e"
5  }
6}

Now that our asset and monitoring set up is done, we move to the next part that deals with capturing the events once they are created. Live Tracking API uses webhooks to share the event information. Let’s see how to configure a webhook.

Step 5: Configure a Webhook

Users need to obtain a webhook URL from their application where they want to receive the information of events created. We, for this example, use a test webhook URL - "https://my-company/api/test_webhook" - to guide users through the process. It is recommended to use an actual webhook URL.

Once we obtain a valid webhook URL, we register it with our Live Tracking API using the (Add or Update Webhook Configuration)[https://docs.nextbillion.ai/docs/tracking/api/live-tracking-api#add-or-update-webhook-configuration] method.

1curl --location --request PUT 'https://api.nextbillion.io/skynet/config?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{ "webhook":[""https://my-company/api/test_webhook""] }'

The webhook registration is acknowledged with an “Ok” response from the API.

Create a Speeding Event

Finally, we will upload tracked GPS information for the asset (received from the device GPS in real-life implementation) and ensure that the asset breaches the speeding configurations that we configured in Step 3. Following is the JSON we use at this step to upload track information:

1curl --location 'https://api.nextbillion.io/skynet/asset/683a3672-8eb3-4ec2-a1b9-1bdc2743d491/track?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{
4    "locations":[
5        {
6        "location":{
7            "lat": 34.04209996,
8            "lon": -118.25563815
9        },
10        "timestamp":1694930360000,
11        "accuracy":2,
12        "speed":12,
13        "bearing":25,
14        "altitude":110.5,
15        "meta_data":{
16            "test": "location 1"
17        }
18        },

As soon as the above locations are uploaded, the speeding criteria of the monitor is satisfied for a couple of locations (location 6 and location 7) and the respective event payloads are received on the configured webhook.

Visit Live Tracking API documentation to know more about the available features