Track arrival, exit, route for geofences

Tracking app users on the move with geofences

Set up geofences when you expect app users to visit a list of places, in no particular order. These could be your offices, partners, branches, or other places of interest that a group of users might visit over the course of the week or month. Or these could be customer or store locations that specific users are expected to visit during the day or week.

Geofences would let you track the arrival and exit at these places, along with time spent in the geofence, and route from one geofence to the other. Use real-time webhooks to automate checkins, checkouts, surveys, visit notes, and other workflows. Use duration and route data to analyze how time is being spent at the place, and getting to the place. Businesses use this data to reward top performing assets and generate real-time producitivity scores. This data may also be used to create better routes and dispatch.

Tracking geofence arrivals and exits via Geofence API

In order to help you with this use case, HyperTrack provides Geofences API that allow you to specify which these locations that you want to be notified about when app user visits.

This API also provides you an ability to manage geofences per app user's device and be notified above geofence enter and exit events as it is tracked during the day.

You may be able to define geofences for the entire fleet of mobile workers. Alternatively, you may pick and choose which app users are expected to visit which locations.

important

Geofence arrival and exit events will only be triggered any time your app user's device is tracked. In order to see how you can start and stop tracking for your device, please see this guide.

Creating geofences for all app users


You can use this Geofences POST API to create a geofence as shown in an example below. Note that you may pass an array of geofence definitions in one API call.

The API supports both Point and Polygon type geofences.

POST   https://v3.api.hypertrack.com/geofences


curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences

In the payload below, you are creating two geofences of Point and Polygon type for all devices under your account. Your account is automatically identified through your AccountId credential supplied in the API call.

{
"geofences": [
{
"geometry": {
"type": "Point",
"coordinates": [ 122.395223, 37.7947633]
},
"metadata": {
"station": "A"
},
"radius": 50
},
{
"geometry": {
"type": "Polygon",
"coordinates": [[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]]
},
"metadata": {
"dropoff": "1ABC"
}
}
]
}

Once the call is made successfully, you will get back an HTTP 200 response with this payload below. Make a note of geofence_id returned below as you will need it to delete this geofence once you no longer need it. You may also use geofence_id to get the details of geofence back as described below.

[
{
"geometry":{
"type":"Point",
"coordinates": [
122.395223,
37.7947633
]
},
"metadata":{
"station": "A"
},
"radius":50,
"single_use": false,
"geofence_id":"000111-4047-4b28-a6ec-f934e870c425"
},
{
"geometry":{
"type":"Polygon",
"coordinates": [
[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]
]
},
"metadata":{
"dropoff": "1ABC"
},
"single_use": false,
"geofence_id":"0002223047-3b28-a8ec-e934e870c515"
}
]

Geofence Creation

Creating geofences for selected app users

In a use case where you want to track certain locations only to be visited by app users that are planned, you are able to supply the corresponding device_id to the Geofence POST API.

POST   https://v3.api.hypertrack.com/geofences

In the payload below, you will notice device_id where we are adding device F3DF6D4F-6A06-4883-8201-D767EA408030 to track with these two geofences that we are defining.

{
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"geofences": [
{
"geometry": {
"type": "Point",
"coordinates": [122.395223, 37.7947633]
},
"metadata": {
"station": "A"
},
"radius": 50
},
{
"geometry": {
"type": "Polygon",
"coordinates": [[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]]
},
"metadata": {
"dropoff": "1ABC"
}
}
]
}

Once the call is made successfully, you will get back an HTTP 200 response with this payload below. Make a note of geofence_id returned below as you will need it to delete this geofence once you no longer need it. You may also use geofence_id to get the details of geofence back as described below.

[
{
"geofence_id":"000111-4047-4b28-a6ec-f934e870c425",
"geometry":{
"type":"Point",
"coordinates": [122.395223, 37.7947633]
},
"metadata":{
"station": "A"
},
"radius":50,
"single_use": false,
},
{
"geofence_id":"0002223047-3b28-a8ec-e934e870c515",
"geometry":{
"type":"Polygon",
"coordinates": [[-122.395237, 37.7947693],
[-122.402321, 37.794374],
[-122.401371, 37.790205],
[-122.389450, 37.791271],
[-122.395237, 37.7947693]]
},
"metadata":{
"dropoff": "1ABC"
},
"single_use": false,
}
]
important

You need to make a note of geofence_id of geofences you created via Geofences API. The geofence_id is the primary handle you need to use to be able yo retrieve geofence events.

Receiving real-time geofence event notifications

Webhook payload is expected to have the following data structure to represent geofence enter and exit events as shown in the example below.

Note that webhook payload can contain multiple entries of type geofence and each geofence event has type geofence. Each geofence event payload inside webhook has data object where you will get value to be either enter or exit. Inside data, you'll also find an arrival and optional exit object, that will get updated as a device enters and leaves a geofence. Each event will be marked with a unique event_id so that you can differentiate them from each other.

Additionally, you will get back metadata you set when creating geofences via API in the webhook payload as well.

[
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"data": {
"event_id": "00001111-3767-2c12-f4ad-e213c130b321",
"value": "entry",
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [122.395223, 37.7947633]
}
"radius":50,
"arrival": {
"location": {
"type":"Point",
"coordinates": [122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
}
"exit": {}
},
"location": {
"type": "Point",
"coordinates": [122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z",
"created_at": "2019-07-01T13:46:00.000000Z",
"version": "2.0.0",
"type": "geofence"
}
]

Geofence Hit with Metadata

Retrieving geofences data and their events

You may be able to retrieve geofence data and and their events as follows:

GET   https://v3.api.hypertrack.com/geofences/{geofence_id}

Note that you are passing geofence_id you previously recorded in the POST call above.

curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/{geofence_id}

When you call for a geofence directly, you will recieve all the data you initialized the geofence with, and an included events object. Each event contains arrival / exit information about that instance of geofence activity and will be ranked in descending order of time.

[
{
"geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"geofence_metadata": {
"station": "A"
},
"geometry": {
"type":"Point",
"coordinates": [122.395223, 37.794763]
}
"radius":50,
"single_use": false,
"events": [
{
"event_id": "00001111-3767-2c12-f4ad-e213c130b321",
"device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
"value": "exit",
"arrival": {
"location": {
"type":"Point",
"coordinates": [122.394223, 37.792763]
},
"recorded_at": "2019-07-01T13:45:00.000000Z"
},
"exit": {
"location": {
"type": "Point",
"coordinates": [122.247904, 57.47385]
},
"recorded_at": "2019-07-01T14:00:00.000000Z"
],
"location": {
"type": "Point",
"coordinates": [122.247904, 57.47385]
},
"recorded_at": "2019-07-01T14:00:00.000000Z",
"created_at": "2019-07-01T14:01:00.000000Z",
"version": "2.0.0",
"type": "geofence"
}
]
}
]

Additionally, you can use Geofences GET API to retrieve a single geofence by geofence_id for the device as shown in an example below:


curl -X GET \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/{device_id}/geofences/{geofence_id}

This call returns a message body of the same structure as above with a single geofence record in the list.

Deleting geofences


You can use Geofences DELETE API to delete a geofence as shown in an example below. Please note you will need to use a specific geofence_id to delete the entry. If the call is successful, you will get HTTP 200 response back.


curl -X DELETE \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/geofences/{geofence_id}

Questions?

If your have requirements to increase operational efficiency of your business assets by tracking arrivals and exits at important locations for your business, questions or comments on any of the topics above, please do not hesitate to contact us.