Enter & Exit Geofence alerts

Products Used: Live Tracking API & Geofence API

NextBillion.ai’s Live Tracking API allows users to monitor their fleet 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 enter or leave a given boundary.

Setup

In this example, we will set up an alerting system which is triggered when the asset enters or exits a given area of interest. We will create an asset, a monitor and a geofence 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:

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 Enter & Exit Event Example",
6            "attributes": {
7                "driver_contact_no": "422-583-651",
8                "driver_name": "John Luther",
9                "license": "2 DS 3236",
10                "vehicle_type": "SUV"
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": "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.

1curl --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 a Geofence

Geofences are geographic boundaries that are used to mark an area of interest. For our example we create a polygon type geofence using NextBillion.ai’s Geofence API.

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:

1curl --location 'https://api.nextbillion.io/geofence?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{
4  "polygon":{
5     "geojson":{
6         "type":"Polygon",
7         "coordinates":[
8             [
9                 [
10                    -118.268312,
11                    34.046253
12                 ],
13                 [
14                    -118.269707,
15                    34.045097
16                 ],
17                 [
18                    -118.270963,

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}

Step 4: Create a Monitor

Now that we have an “asset” and a “geofence”, 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 “enter_and_exit”.
• Specify the ID of the geofence that we want to use for creating events.
• 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": "enter_and_exit",
5  "geofence_config": {
6    "geofence_ids": [
7      "7d1b861c-67b8-4128-aef8-179a605263c4"
8    ]
9  },
10  "name": "Monitor The Ritz Hotel, Los Angeles",
11  "description": "Track activity related to free staff transportation service",
12  "match_filter": {
13    "include_all_of_attributes": {
14      "driver_contact_no": "422-583-651",
15      "driver_name": "John Luther",
16      "license": "2 DS 3236",
17      "vehicle_type": "SUV"
18    }

Please record the monitor ID from the API response:

1{
2  "status": "Ok",
3  "data": {
4    "id": "dae3b4bd-2402-4b53-83dd-c094b79d02cc"
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.

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) and ensure that it reaches to a point inside the geofence that we created in Step 3. Following is the JSON we use at this step to upload track information:

1curl --location 'https://api.nextbillion.io/skynet/asset/eb51687b-2f1d-4a50-bae5-73a6d6e5e77f/track?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{
4  "locations": [
5    {
6      "location": {
7        "lat": 34.045012,
8        "lon": -118.269904
9      },
10      "timestamp": 1694930400000,
11      "accuracy": 2,
12      "speed": 5,
13      "bearing": 25,
14      "altitude": 110.5,
15      "meta_data": {
16        "test": "location_outside_geofence"
17      }
18    },

As soon as the first location inside the geofence is uploaded the “enter” criteria of the monitor is satisfied and an event payload is received on the configured webhook.

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