Receive Speeding Alerts

Live Tracking API can be used to get real time alerts based on asset movement and activity. In this example we will present a step by step guide of how to receive events on a configured webhook, when an asset is idle or not moving as desired.

Get Started

Readers would need a valid NextBillion API key to try this example out. If you don’t have one, please contact us to get your API key now!

Setup

Once you have a valid API Key, you can start setting up the components to be used in this example. Let’s take a look at them below.

Step 1: Create Asset

Having received a valid key, let’s kick start the setup process by creating an asset whose activity we want to track. To create an asset, we will

• Give a meaningful name to asset

• Add the attributes of the asset that will be used to associate the asset to a monitor

• Though we are not specifying any custom ID in this example, but user’s can provide a custom ID to the asset, if preferred.

Following is the Asset JSON that is used for this example:

1
curl --location 'https://api.nextbillion.io/skynet/asset?key=<your_api_key>'
2
--header 'Content-Type: application/json' --data '{...}'

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. Please note that the same device can be used for multiple assets, but one asset can be attached to only one device at a time.

1
curl --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:

1
{
2
  "status": "Ok"
3
}

Step 3: Define the Speeding 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 from the asset to determine the speed maintained by the asset for a given amount of time.

The rules for speeding state are set using three attributes - time_tolerance, customer_speed_limit and use_admin_speed_limit. The amount of time for which an asset needs to over-speed before triggering a speeding alert is set using time_tolereance. For speed limits, users have a choice to select which type speed limit is used for monitoring. If they prefer custom speeds, then they can use customer_speed_limit to specify the desired speeds while keeping the use_admin_speed_limit flag as false. Otherwise, they can set the use_admin_speed_limit flag to true to use administrative speed limits for monitoring.

For our example, we are using custom speed limits and configure a speed of 18 m/sec as the threshold and set the use_admin_speed_limit as false. Readers encouraged to try the administrative speed limits as well. Next, we set the time_tolerance at 35000 milliseconds (i.e. 35 sec). It is worth highlighting here that in order to create a speeding event, the asset needs to maintain a higher speed continuously for a duration more than the time_tolerance duration. If the speed of the asset is equal to or if it falls below the speed limit, the asset is not considered to be speeding. We will cover a scenario to showcase this in the Create Speeding Alert section.

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
}

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. Since we want to track overspeeding instances of the asset, we set this value to speeding.

• Specify the speeding_config attributes to model the configurations decided in the Step 3 above. This configuration will be used by the monitor to identify instances of overspeeding.

• Ensure that asset is successfully linked with monitor. It is worth noting that only those assets which share all of their attributes with a monitor are linked with it. For our example, we add the same attributes for the monitor as that of the asset for the sake of simplicity.

• Optionally, add name and description for the monitor.

Below is the JSON we built for creating the monitor:

1
curl --location 'https://api.nextbillion.io/skynet/monitor?key=<your_api_key>'
2
--header 'Content-Type: application/json' --data '{...}'

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

Readers should obtain a webhook URL from their application where they want to receive the information of events created. In our example, we are using a webhook URL provided by a messenger. Using this webhook results in the event information being sent to the messenger as a notification whenever an event is created.

Although we use a test webhook URL - https://my-company/api/test_webhook - in this tutorial to guide readers through the process, we recommend using an actual webhook URL while trying this tutorial

Once we obtain a valid webhook URL, we register it with our Live Tracking API using the Add or Update Webhook Configuration method.

1
curl --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 registration is acknowledged with an Ok response from the API.

Step 6: Test the webhook

In order to make sure that our webhook is correctly configured and is ready to receive the event information, let’s test it out. We will send a test request using our Test Webhook Configuration method and check if a sample event was received on the webhook or not.

1
Test request: curl --location --request POST 'https://api.nextbillion.io/skynet/config/testwebhook?key=<your_api_key>'

Upon sending the above request we received the following sample event on the registered webhook:

1
{
2
"asset_id":"f1ceb76d-2665-4f72-bc56-aae91c4953e3",
3
"geofence_id":"350706bf-cc3b-4e74-a66c-c7f050944c47",
4
"monitor_id":"8a8ecd4b-f8b2-49ed-8097-b114ce53e4db",
5
"monitor_tags":["america","newyork"]
6
}

Create Speeding Event

Now that setup is done, let’s start uploading the locations for the asset’s movement. We will upload a series of locations to demonstrate how speeding events work. In a practical scenario, however, these updates would be automatically sent by the GPS device that is bound to the given asset.

Let’s take a look at following list of sample locations and their attributes:

Before we analyze the above data, remember we configured time_tolerance at 35000 milliseconds (35 seconds) and customer_speed_limit at 18 m/s as speeding state configurations in our monitor. From the above table we can observe that, speed does exceed 18 m/s threshold at location 2 and the timer starts, but since the speed at next location falls below the speed limit, the timer resets to 0 at location 3. Had the speed at location 3 been more than the speed limit, timer would have accumulated the seconds elapsed after location 2.

However, from location 4 onwards the asset is continuously traveling at a speed more than 18 ms/s until location 7. The timer also starts from location 4 and continues to accumulate seconds through locations 5, 6 and 7. The speeding alert is created for locations 6 and 7 as both speed value and timer value at these locations are greater than specified thresholds of 18 m/s and 35 seconds respectively. Do note that location 5 does not trigger the event as the timer value is still lower than time_threshold. Timer resets to 0 at location 8 as the speed falls below the speed limit.

The above track distribution when modeled into a upload JSON results in below script:

1
curl --location 'https://api.nextbillion.io/skynet/asset/683a3672-8eb3-4ec2-a1b9-1bdc2743d491/track?key=<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

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 following events are received on our configured webhook.

First Speeding Event payload

1
{
2
"asset_id":"683a3672-8eb3-4ec2-a1b9-1bdc2743d491",
3
"geofence_id":"",
4
"monitor_id":"36c171d5-bdf1-47c2-9531-4c02820ab70e",
5
"monitor_tags":[],
6
}

Second Speeding Event payload

1
{
2
"asset_id":"683a3672-8eb3-4ec2-a1b9-1bdc2743d491",
3
"geofence_id":"",
4
"monitor_id":"36c171d5-bdf1-47c2-9531-4c02820ab70e",
5
"monitor_tags":[],
6
}