Track arrival, exit, route to Geofences

Introduction

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 commercial areas 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.

You can get started with geofences at the following level of granularity:

Account-wide or group-wide geofences

Account-wide or group-wide geofences can represent hubs, warehouses, daily checkpoints, dark stores, or locations where all users in a region are expected to visit many times over. By creating geofences accessible by all app users, you can log the throughput of these areas and track stats for them over time. Visit this section to get started.

Group-wide geofences

Group-wide geofences represent places that a specific group of users are expected to access. By attaching a metadata filter to your geofences, you can restrict events logged for that geofence to only those app users who are registered with the same metadata key and value. This is a helpful strategy to segment app users activity to a network of geofences. Visit this section to get started.

User-specific geofences

These geofences represent places that a user is expected to visit during the day, week, or month. A user may have a route assigned to them with places to visit along the path. By creating geofences for a specific user, you may assign places like customer's addresses, drop-off points, delivery checkpoints and track stats for them over time. Visit this section to get started.

Work-specific geofences

These geofences are targeted for use cases where you may have a customer or partner locations where work needs to be performed once. To get started with work-specific geofences you simply specify them with trip creation. Read more about creating geofences here to get started.

Track arrival, exit, and route to geofences only during work hours

To track app users only during work hours, use Devices API to start and stop tracking for their devices.

HyperTrack Devices APIs give you the power to control tracking on all devices using apps with HyperTrack SDKs pointing to your account. As you perform Device API calls from your servers, you are can remotely start and stop tracking devices with apps running HyperTrack SDK integration.

In order to perform API calls from your server, you need to first obtain AccountId and Secret Key.

Start tracking

For example, if you would like to start tracking when your app at the start of working hours, or work assignment, or app login, you may want to call Devices API call to start tracking for your device. In order to start tracking on your device, you should be able to obtain, store, and reference your users' HyperTrack device_id when calling this API from your server.

To start tracking your device, you may make a Devices API call as shown below.

// Instantiate Node.js helper library instance
const hypertrack = require("hypertrack")(accountId, secretKey);
// Use Node.js helper library method to start tracking
hypertrack.devices
    .startTracking(deviceId)
    .then(() => {
        // Tracking started
    })
    .catch(error => {
        // Error handling
    });

Stop tracking

In order to protect the privacy of workers using your app, you are strongly encouraged to stop tracking when the user either logs out, ends working hours, completes all assigned work, etc. To do so, you may make a Devices API stop tracking call. Once you issue this call from the server, HyperTrack Device API will remotely stop tracking for your device with device_id.

// Instantiate Node.js helper library instance
const hypertrack = require("hypertrack")(accountId, secretKey);
// Use Node.js helper library method to stop tracking
hypertrack.devices
    .stopTracking(deviceId)
    .then(() => {
        // Tracking started
    })
    .catch(error => {
        // Error handling
    });

Get the device ID(s) of the user(s) you want to track

The SDK should have added a device name and metadata upon initialization in the user's app: (iOS, Android).

If you have already sent and stored this information to your servers, get the user's device ID from your application database. Else, get the list of registered devices from the Devices API and use the device name or metadata to identify the user(s) you want to track.

HyperTrack views and developer integrations rely on the device names and metadata for filtering, selection, and more. Customizing these device properties makes navigation and identification of users easier. Developers often add unique identifiers, grouping information, or annotations that are frequently accessed for devices.

Device name and custom metadata

{
    "name": "Alex’s Phone",
    "metadata": {
        "customer_id": "ABC123"
    }
}

By default, the property name is set to the name of the device as configured in the device settings. With the SDK, you can set and customize this name. Additionally, the Devices API provides you an ability to update device name and metadata via an HTTP PATCH.

note

The Devices API is authoritative when it comes to setting the device name and/or metadata. Once you have updated the device name by invoking the Devices API above, the HyperTrack mobile SDK will not be able to make subsequent changes to the device name. Similarly, if you update the device metadata via the Devices API call, the HyperTrack mobile SDK will not be able to make changes as well.

Create geofences

Use Geofences API to specify areas for which you want to track arrivals, exits, durations and routes to.

Geofences may be created for all app users in the fleet or specific app users expected to visit these areas.

important

Geofence arrival and exit markers will only be triggered when the device is tracking. In order to see how you can start and stop tracking for your device, please see this guide.

Creating geofences for all app users

App users may visit common areas like warehouses, daily checkpoints, or dark stores. By creating geofences accessible by all app users, you can log the throughput of these areas and track stats for them over time.

To create geofences for all app users, use the Geofences POST API as shown in the example below. Note that you may pass an array of geofences 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 201 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":"00002222-3738-1c11-f2ef-a213e641a342"
   }
]

Geofence Creation

Creating geofences for groups of app users

App users may visit shared areas like warehouses, or dark stores. By creating geofences accessible by a group of app users, you can restrict the logging of that geofence's stats to app users that have the configured metadata key and value attached.

To create geofences for all app users, use the Geofences POST API as shown in the example below. Note that you may pass an array of geofences 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, both accessible by app users that have the "foreman" as "Bruce Lee". 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"
            }
        }
    ],
    "metadata_filter": {"foreman": "Bruce Lee"}
}

[
   {
      "geometry":{
          "type":"Point",
          "coordinates": [
            122.395223,
            37.7947633
          ]
      },
      "metadata":{
         "station": "A"
      },
      "radius":50,
      "single_use": false,
      "geofence_id":"000111-4047-4b28-a6ec-f934e870c425",
      "metadata_filter": {"foreman": "Bruce Lee"}
   },
   {
      "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":"00002222-3738-1c11-f2ef-a213e641a342",
      "metadata_filter": {"foreman": "Bruce Lee"}
   }
]

Creating geofences for specific app users

A user may have commonly visited places where auto-check in is desired. By creating geofences for a specific user, you may assign static places like customer's addresses and track stats for them over time.

To create geofences for specific app users, use the Geofences POST API with the corresponding device_id.

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

In the payload below, you will notice the device_id field where device F3DF6D4F-6A06-4883-8201-D767EA408030 will be tracked for the two geofences created.

{
    "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"
            }
        }
    ]
}

[
   {
        "geofence_id":"000111-4047-4b28-a6ec-f934e870c425",
        "device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
        "geometry":{
            "type":"Point",
            "coordinates": [-122.395223, 37.7947633]
        },
        "metadata":{
            "station": "A"
        },
        "radius":50,
        "single_use": false,
    },
    {
        "geofence_id":"00002222-3738-1c11-f2ef-a213e641a342",
        "device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
        "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 modify or query it later.

Geofence Hit Clusters

Creating work-related geofences for specific app users

A user may have a route assigned to them with places to visit for the work dat. By creating geofences for a specific user, you may assign one-time places like customer's addresses, drop-off points, delivery checkpoints and track stats over the course of the work day.

To create work related geofences for specific app users, create a trip with the corresponding device_id and include a list of geofences the app user is expected to visit.

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

In the payload below, you will notice the device_id field where device F3DF6D4F-6A06-4883-8201-D767EA408030 will be tracked for the two geofences created.

{
    "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"
            }
        }
    ],
    "metadata": {"name": "a trip with two geofences"}
}

Once the call is made successfully, you will get back an HTTP 201 response with details about the trip.

Geofence markers

As your geofences get visited by app users, it's critical to understand how they got there and how they spent their time. A marker is created when an app user arrives at a geofence, and is edited when they exit. The next section covers how you can receive geofence arrivals and exits over webhooks, query who last visited a specific location, and add metadata to a marker.

Inside each geofence marker, you'll also find an arrival and optional exit object that will get continuously updated as an app user arrives and exits a geofence. Each marker will be tagged with a unique marker_id so that you can differentiate them from each other.

When your users arrive at a geofence, an object called route_to will be initialized if there was a previous geofence that they came from. Inside the route_to object you'll find attributes duration and distance that give metrics on how long and how far the journey was. Please note that a geofence will be initialized with a route_to object even if the previous geofence has not been exited.

After your user leaves the geofence, the marker will be updated with its own duration attribute for how they spent inside.

Receiving real-time arrival and exit notifications

By subscribing to geofences, you can receive a real-time stream of your app user's geofence arrivals and exits, so you can flag anomalies right as they happen.

The webhook payload is expected to have the following data structure to represent geofence arrivals and exits as shown in the example below. Note that webhook payload can contain multiple entries, each with type geofence. Each geofence marker payload inside webhook has a data object containing a an arrival or exit corresponding to the state of the geofence. arrival will be shown by default, as a marker starts when a device enter a geofence. exit will be included when the device leaves that geofence.

[
    {
        "device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
        "data": {
            "geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
            "marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
            "metadata": null,
            "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": {},
            "duration": null,
            "route_to": {
                "duration": 3600,
                "distance": 2374
            },
            "value": "entry"
        },
        "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"
    }
]

note

The value attribute in the data object is a legacy field and contains some inconsistent terminology to what is currently given in the response. The value of entry corresponds to the arrival object. The value of exit is unchanged and corresponds to its exit.

Geofence Hit Real Time with Metadata

Retrieving markers for a geofence

By accessing the marker stream of your configured geofences, you can see which of your app users last visited, and for how long. You may query a geofence for all markers from app users that have permission to hit it.

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

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

The JSON response contains two keys data and links, where data contains an array of markers ordered in descending time, and links contains a url to retrieve the next page of results. If there is not a next page found, the next object will be null.

{
    "data": [
        {
            "geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
            "device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
            "marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
            "metadata": null,
            "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.154223, 37.132763]
                },
                "recorded_at": "2019-07-01T13:50:00.000000Z"
            },
            "duration": 900,
            "route_to": {
                "duration": 3600,
                "distance": 2374
            },
            "value": "exit"
        },
        {
            "geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
            "device_id": "A2DA5B2A-1B23-1244-1235-A134BD212415",
            ...
        }...
    ],
    "links": {
        "next": 'https://v3.api.hypertrack.com/geofences/markers?geofence_id=00001111-4047-4b28-a6ec-f934e870c425&pagination_token=eyJhY2NvdW50X2lkIj'
    }
}

note

Retrieving markers for selected app users

Did your app user visit all the geofences tasked to them today? By dialing the API to a single app user, you may recieve a stream of markers containing all of the geofences they hit.

GET https://v3.api.hypertrack.com/geofences/markers?device_id={device_id}

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

{
    "data": [
        {
            "geofence_id": "00001111-4047-4b28-a6ec-f934e870c425",
            "device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
            "marker_id": "00001111-3767-2c12-f4ad-e213c130b321",
            "value": "exit",
            "metadata": null,
            "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.154223, 37.132763]
                },
                "recorded_at": "2019-07-01T13:50:00.000000Z"
            },
            "duration": 900,
            "route_to": {
                "duration": 3600,
                "distance": 2374
            }
        },
        {
            "geofence_id": "00002222-3738-1c11-f2ef-a213e641a342",
            "device_id": "F3DF6D4F-6A06-4883-8201-D767EA408030",
            ...
        }...
    ],
    "links": {
        "next": 'https://v3.api.hypertrack.com/geofences/markers?device_id=F3DF6D4F-6A06-4883-8201-D767EA408030&pagination_token=eyJhY2NvdW50X2lkIj'
    }
}

note

Changing metadata of markers

What happened at the time of a geofence hit? By patching the metadata of your markers, you can tell the story with notes and custom business attributes.

You can use the Geofences PATCH API to modify any geofence at any time after its creation.

PATCH https://v3.api.hypertrack.com/geofences/markers/{marker_id}

payload='{
  "metadata": {
    "message": "Package left at the door",
    "tracking_id": "384748984"
  }
}'

curl -X PATCH \
  -u {AccountId}:{SecretKey} \
  https://v3.api.hypertrack.com/geofences/markers/{marker_id}
  -H 'Content-Type: application/json' \
  -d $payload

Retrieving and Modifying geofences data

Once a geofence has been created, you have many options for retrieving that information back. You can retrieve data for a single geofence, geofences set for an entire fleet of mobile workers, or geofences that are set for selected app users.

Retrieving a single geofence

You may be able to retrieve geofence data for a particular geofence_id like so:

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

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

[
    {
        "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
    }
]

Retrieving geofences set for all app users

You can also use the Geofences GET API to retrieve geofences that are set for all devices:

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

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

The JSON response contains two keys data and links, where data contains an array of geofence objects, and links contains a url to retrieve the next page of results. If there is not a next page found, the next object will be null.

{
    "data": [
        {
            "geofence_id": "00001111-4047-4b28-a6ec-f934e870c425"
            "geofence_metadata": {
                "station": "A"
            },
            "geometry": {
                "type":"Point",
                "coordinates": [122.395223, 37.794763]
            }
            "radius":50,
            "single_use": false
        }
    ],
    "links": {
        "next": 'https://v3.api.hypertrack.com/geofences/?pagination_token=eyJhY2NvdW50X2lkIj'
    }
}

To access the next page of data, simply perform another GET request to the next url provided in the JSON response:

GET https://v3.api.hypertrack.com/geofences/?pagination_token=eyJhY2NvdW50X2lkIj

Retrieving geofences set for selected app users

Additionally, you can use Geofences GET API to retrieve all geofences created for a device as shown in an example below:

GET https://v3.api.hypertrack.com/geofences/?device_id={device_id}

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

The JSON response is the same as the object listed above with data and links keys. You can paginate through this response's pages using the same method described previously.

Modifying metadata of geofences

Over the course of a geofence's lifetime, you may want to change its attributes to reflect that of your internal system. Or, you want to leave a note for the next app user that visits this location.

You can use the Geofences PATCH API to modify any geofence at any time after its creation. Metadata for this geofence will be changed and visible across all HyperTrack views. Please note that previous metadata will be erased after you update it.

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

payload='{
  "metadata": {
    "Assign": "Riley Davis",
    "Note": "Access from the back parking lot"
  }
}'

curl -X PATCH \
  -u {AccountId}:{SecretKey} \
  https://v3.api.hypertrack.com/geofences/markers/{marker_id}
  -H 'Content-Type: application/json' \
  -d $payload

Deleting geofences

You may delete geofences that are no longer needed. Geofences that are deleted will not have their markers deleted and will still show up in the views. Deleted geofences cannot be hit by any devices after the time of deletion.

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 areas for your business, questions or comments on any of the topics above, please do not hesitate to contact us.

Introduction#

Account-wide or group-wide geofences#

Group-wide geofences#

User-specific geofences#

Work-specific geofences#

Track arrival, exit, and route to geofences only during work hours#

Start tracking#

Stop tracking#

note

Create geofences#

important

Creating geofences for all app users#

Creating geofences for groups of app users#

Creating geofences for specific app users#

important

Creating work-related geofences for specific app users#

Geofence markers#

Receiving real-time arrival and exit notifications#

note

Retrieving markers for a geofence#

note

Retrieving markers for selected app users#

note

Changing metadata of markers#

Retrieving and Modifying geofences data#

Retrieving a single geofence#

Retrieving geofences set for all app users#

Retrieving geofences set for selected app users#

Modifying metadata of geofences#

Deleting geofences#

Questions?#

Introduction

Account-wide or group-wide geofences

Group-wide geofences

User-specific geofences

Work-specific geofences

Track arrival, exit, and route to geofences only during work hours

Start tracking

Stop tracking

Create geofences

Creating geofences for all app users

Creating geofences for groups of app users

Creating geofences for specific app users

Creating work-related geofences for specific app users

Geofence markers

Receiving real-time arrival and exit notifications

Retrieving markers for a geofence

Retrieving markers for selected app users

Changing metadata of markers

Retrieving and Modifying geofences data

Retrieving a single geofence

Retrieving geofences set for all app users

Retrieving geofences set for selected app users

Modifying metadata of geofences

Deleting geofences

Questions?