/ operations monitoring

Mapping your organization with Groups

The HyperTrack API is used by forward thinking organizations of all sizes to make their location and activity data more useful. Many of these organizations have hierarchical structures that need to be represented in the API. Often times, these structures also define access control rules: who can access what data.

Today, we are releasing new features that make this possible. In this post, we cover how to use them in your integrations, and show examples of how this can be useful.


A tree of groups

Every device that is tracked through the HyperTrack mobile SDK is identified through the User entity. In addition, User objects can belong to Group objects. Now, we have extended the Group entity to support hierarchical organizations.

A hierarchy of groups is a tree, and we use adjacency lists to represent the data structure. An adjacency list stores tuples of parent-child relations, where each child element stores a reference to the parent group. The group diagram above can be modeled as an adjancency list as shown below.

Group name Parent group name
San Francisco California
Los Angeles California
Sacramento California
Berkeley San Francisco
Palo Alto San Francisco

Let's take a quick look at how this can be used in the API. First, let's create a Group object that represents the parent group.

curl -H "Authorization: token SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"name": "California"}' \

    "id": "900ddb74-1a0c-49b6-84de-e7746dfec298",
    "name": "California",
    "unique_id": "GROUP001,
    "parent_group_id": null,
    "token": "gk_e8b6ee3dc08327e3e504511386a1954605bea90d",
    "created_at": "2017-09-04T18:04:12.627006Z",
    "modified_at": "2017-09-04T18:04:12.634942Z"

Next, create the child group. The Group entity in the HyperTrack API has a property called the parent_group_id, where we will save the identifier of the parent group. This will establish the parent-child relationship in the adjacency list.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{"name": "Los Angeles", "parent_group_id": "900ddb74-1a0c-49b6-84de-e7746dfec298"}' \

    "id": "1fe35f12-a453-4a7f-8e49-83f863c92c5f",
    "name": "Los Angeles",
    "unique_id": "GROUP002",
    "parent_group_id": "900ddb74-1a0c-49b6-84de-e7746dfec298",
    "token": "gk_41be9032e48ad0e2f12492320417290773410949",
    "created_at": "2017-09-04T18:05:23.056919Z",
    "modified_at": "2017-09-04T18:05:23.063959Z"

If you have existing Group objects, you can also update them through other API calls.


With your organization structure in place, you can get group level visualizations. These visualizations will restrict data access to the group's sub-tree, viz. data of users in the group or one of its children. You can add team members with group-level permissions to the HyperTrack dashboard, or embed group-level widgets in your internal dashboards.

Group-level dashboard access

When adding members to your HyperTrack account, you can select the Group that they will have access to. Once set up, team members can login through the desktop or mobile dashboard, and see data for the group sub-tree.

Team member groups

Group-level embeddable widgets

If you prefer, every HyperTrack Dashboard view can also be embedded as a widget. Every Group object has a corresponding read-only token, which can be used to setup the widget view.

  1. Retrieve the Group object to get the token property. These tokens look like gk_xyz123, but are much longer.
  2. Choose the widget that you would like to embed.
  3. Pass the token to your widget url, and embed the view as an iframe in your internal dashboard.
<iframe src="https://dashboard.hypertrack.com/widget/map/users?key=gk_55fc65eb64c0b10300c54ff79ea3f6ef22981793">

Once the iframe is integrated, the widget gets embedded as shown below. You can play around with this live example.


You may also use groups to distribute events via webhooks or Slack alerts. For example, you can set the group while defining a Slack alert, so that this Slack URL only receives events for a specified group. This way you can route events to different Slack channnels.


With hierarchical groups, our API is more composable to satisfy a variety of use cases. Tell us how we can help you map your organization to our API entities, so that you can see it live on a map!