Real-time order alerts

Products Used: Live Tracking API & Geofence API

NextBillion.ai’s Live Tracking API allows users to monitor their vehicles in real-time and receive alerts as well when the desired vehicles are arriving at or have departed from the locations of interest. Users can set up custom geographical boundaries using NextBillion.ai’s Geofence API and then use them in Live Tracking service for receiving alerts when the configured vehicles exhibit a desired activity.

In this example, we will set up an alerting system which triggers an alert when the delivery van leaves the restaurant and when the van is about to reach its delivery location. We will create an asset, two monitors and two geofences to achieve this. Let’s go through the following steps to set-up a location based real-time 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:

1
curl --location 'https://api.nextbillion.io/skynet/asset?key=<your_api_key>' --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": "eb51687b-2f1d-4a50-bae5-73a6d6e5e77f"
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.

1
curl --location 'https://api.nextbillion.io/skynet/asset/eb51687b-2f1d-4a50-bae5-73a6d6e5e77f/bind?key=<your_api_key>' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "device_id":"APL-14-iOS-X43V21F"
5
}'

As soon as the binding process is successful, we get an acknowledgement response from the API. Next we will set up geofences to mark the boundaries which will trigger the alerts.

Step 3: Set up Geofences

Geofences are geographic boundaries that are used to mark an area of interest. For our example we create two geofences - one of them will be of polygon type around the delivery location and other will be of circle type around the restaurant’s location. We will use NextBillion.ai’s Geofence API to create them.

For the polygon geofence around the delivery location, we specify:

The “type” of the geofence as “polygon”
“name” of the geofence
“geojson” object with details of the coordinates forming the polygon. If the readers are creating their own polygons, it is worth mentioning that the geofence should be closed, not contain any intersecting boundaries, and should not contain other polygons.

Below is the Create a Geofence JSON script we use for this example

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

Once the geofence is created, we get the geofence ID in the acknowledgement response. Please record this ID.

1
{
2
  "status": "Ok",
3
  "data": {
4
    "id": "7d1b861c-67b8-4128-aef8-179a605263c4"
5
  }
6
}

Next, we will create the circle type of geofence around the restaurant, by specifying:

a center specifying the center of the geofence. We specify the restaurant’s location coordinates here
define the radius of the circular geofence
set the type of the geofence as “circle”.
add meaningful tags, meta_data and name

Below is the Create a Geofence JSON script we use for this example:

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

Once the geofence is created, we get the geofence ID in the acknowledgement response. Please record this ID as well.

1
{
2
  "status": "Ok",
3
  "data": {
4
    "id": "52bb7d98-c5db-4210-99a0-60622764b6fc"
5
  }
6
}

Step 4: Create Monitors

Now that we have an “asset” and a “geofence”, let’s set up a monitoring criteria using a monitor. We will need to create two monitors for our example. One monitor will be to create enter events when the delivery van is close to the delivery location. The other monitor will be for creating exit events when the van leaves the restaurant.

To create an enter monitor, we need to:

specify the type as “enter”.
specify the ID of the geofence that we created around the delivery location
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 this monitor:

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

Please record the monitor ID from the API response:

1
{
2
  "status": "Ok",
3
  "data": {
4
    "id": "33cd7b90-e105-4a0d-9bd2-284ac426fc0f"
5
  }
6
}

Now we will set up another monitor which will track the exit activity of the asset after it starts from the restaurant’s locations. We specify:

specify the type as “exit”.
specify the ID of the geofence that we created around the restaurant’s location
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 this monitor:

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

Please record the monitor ID from the API response:

1
{
2
  "status": "Ok",
3
  "data": {
4
    "id": "d94218b9-7755-4150-8dcd-aec152dd9bc3"
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 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 webhook registration is acknowledged with an “Ok” response from the API.

Step 6: Upload track information

Finally, we will upload locations for the asset (which would be received as pings from the device GPS in real-life implementation) as it moves through its trip from the restaurant to the delivery location. Following is the JSON we use at this step to upload track information:

1
curl --location 'https://api.nextbillion.io/skynet/asset/eb51687b-2f1d-4a50-bae5-73a6d6e5e77f/track?key=<your_api_key>' --header 'Content-Type: application/json' --data '{...}'

As soon as the first location outside the restaurant’s geofence is uploaded the “exit” criteria of the monitor is satisfied and an event payload is received on the configured webhook. Same happens as the first location inside the delivery location’s geofence is uploaded triggering the “enter” event.

Visit product documentation (Live Tracking API | Geofence API) to know more about the available features.