User

The User object represents the user who is being tracked. Every SDK instance needs to be initialised with a user to identify the mobile device.

User properties

A User object consists of following data.

Properties set by you when creating users

Property Type Description
unique_id String Unique identifier for the user in your system
group_id String Identifier for the collection of users in your system. See below for details.
name String Name of the user
phone String E164 formatted phone number of user
photo String URL where the profile photo of this user is hosted
metadata JSON Custom key-values pairs in your system that you want to associate with the user. E.g. Car - Honda Accord
Groups

Group is a collection of Users. Groups support hierarchy, and can contain sub-groups. Examples:

  • A group of employees who belong to a certain organization
  • A group of consumers who live in a particular city

Properties computed by HyperTrack

Property Type Description
id UUID String Unique identifier for the user object created by HyperTrack when user was created
group JSON Object of group of which user is part of
created_at ISO datetime string Time when user object was created
is_tracking Boolean true if the user is currently getting tracked; false if not
last_heartbeat_at ISO datetime string Time when we last heard from the device. It will be different from the time when location was last updated
location JSON Object with live location of user. Will consist of lat-long and time when that location was recorded. Will be null if is_tracking for that user is false
activity JSON Object with live activity of user. Will consist of activity type and time when that activity started. Will be null if is_tracking for that user is false
health JSON Object with live device health. Will consist of battery %, battery status, location status and network status. Will be null if is_tracking for that user is false

Sample JSON

{
      "id": "406c1b6e-b23b-4cb2-94b2-94b76adf23d8",
      "unique_id": "alex-26",
      "group": null,
      "name": "Alex Markham",
      "phone": null,
      "photo": "https://hypertrack-api-v2-prod.s3.amazonaws.com/default_drivers/v2/a11.png",
      "is_tracking": true,
      "created_at": "2017-12-28T12:27:47.530837Z",
      "activity": {
          "type": "unknown",
          "unknown_reason": "",
          "started_at": "2018-03-21T06:37:29.841000Z",
          "ended_at": null,
          "steps": 0
      },
      "location": {
          "geojson": {
              "type": "Point",
              "coordinates": [
                  77.6328515,
                  12.9288829
              ]
          },
          "recorded_at": "2018-03-21T06:37:34.689000+00:00"
      },
      "health": {
          "battery_percentage": 13,
          "location_status": "location_available",
          "battery_status": "unknown",
          "network_status": "network_offline"
      },
      "last_heartbeat_at": "2018-03-21T06:37:34.710000Z"
  }

}

APIs to program users

API call Method URL Description
Create users users/ Create one or more users
Update a user users/<id>/ Edit a user object
Get a user users/<id>/ Get a user object
Get multiple users users/ Lists all user objects. Use parameters to filter and order

Create users

This API will create and return a User object.

HTTP Request

POST https://api.hypertrack.com/api/v2/users/

Parameters

See the list of parameters that you can pass. All parameters are optional.

Returns

Returns a user object if the call succeeded.

curl -H "Authorization: token PUBLISHABLE_KEY" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"name\": \"User name\", \"phone\": \"+16502469293\"}" \
     https://api.hypertrack.com/api/v2/users/
hypertrack.User.create(
    name='Steve Smith',
    phone='+16502469293'
)
HyperTrackClient client = new HyperTrackClient("PUBLISHABLE_KEY");
UserFactory userFactory = new UserFactory(client);
Map<String, Object> params = new HashMap<>();
params.put("name", "Steve Smith");
params.put("phone", "+16502469293");
User user = userFactory.create(params);
HyperTrack::User.create(name: "Steve Smith", phone: "+16502469293")
hypertrack.user.create({
    name: 'Steve Smith',
    phone: '+16502469293'
})

Update a User

Edit an existing user object.

HTTP Request

PATCH https://api.hypertrack.com/api/v2/users/<id>/

Returns

Returns the updated user object.

Parameters

See the list of parameters that you can pass. All parameters are optional.

curl -H "Authorization: token PUBLISHABLE_KEY" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"name\": \"User name\", \"phone\": \"+16502469293\"}" \
     https://api.hypertrack.com/api/v2/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
user.name = 'New name'
user.photo = 'https://photo-url.com/photo.png'
user.save()
HyperTrackClient client = new HyperTrackClient("PUBLISHABLE_KEY");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");

Map<String, Object> newParams = new HashMap<>();
newParams.put("name", "New name");
newParams.put("photo", "https://photo-url.com/photo.png");

userFactory.patch(user, newParams);
hypertrack.user
    .update(
        "d0ae4912-2074-45ef-a7c0-76be58639ea9",
        {
            "name": "New name",
            "photo": "https://photo-url.com/photo.png"
        }
    );

Get a User

Get the user with ID given in the request URL.

HTTP Request

GET https://api.hypertrack.com/api/v2/users/<id>/

Returns

Returns a user object if the call succeeded.

curl -H "Authorization: token PUBLISHABLE_KEY" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
HyperTrackClient client = new HyperTrackClient("PUBLISHABLE_KEY");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");
HyperTrack::User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
hypertrack.user
    .retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9")
    .then(function(user) {})

Get multiple users

Get all user objects based on chosen parameters.

HTTP Request

GET https://api.hypertrack.com/api/v2/users/

Returns

Returns a list of users.

Parameters

You can use any of the optional parameters to filter and/or order the action list.

curl -H "Authorization: token SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/users/
users = hypertrack.User.list()
hypertrack.user
    .list()
    .then(function(users){});
HyperTrackClient client = new HyperTrackClient("SECRET_KEY");
UserFactory userFactory = new UserFactory(client);
HyperTrackArrayList<User> users = userFactory.list();
HyperTrack::User.list

APIs to get data for common use cases

API call Method URL Description Use cases
Mileage tracking users/<id>/mileage/ Get mileage for a user based on chosen parameters. By default, mileage is computed for the current date. Mileage tracking
Placeline users/<id>/placeline/ Get placeline and location_time_series for user Operations monitoring

Mileage tracking

Tell us if you need this API, we will prioritise its development

Get mileage for a user based on chosen parameters. By default, mileage is computed for the current date if no parameter is passed.

Parameters

If you need to mileage for a date range, pass min_recorded_at and max_recorded_at in the parameters.

Parameter Type Description
min_recorded_at ISO datetime string The date/time from which you want the mileage
max_recorded_at ISO datetime string The date/time to which you want the mileage
HTTP Request

GET https://api.hypertrack.com/api/v2/users/<id>/mileage/

curl -H "Authorization: token PUBLISHABLE_KEY" \
     -X POST \
Returns

Returns a paginated list of objects, one for each user that gets filtered with the query parameters. Each object in the response contains the user object and additional mileage data.

Property Type Description
min_recorded_at ISO datetime string Parameter passed in request
max_recorded_at ISO datetime string Parameter passed in request
action_count Integer Number of actions that were completed by the user between the two timestamps passed in the parameters
duration_by_activity JSON Time difference, in seconds, split by activity type. In the JSON, each key is an activity type and the value is the duration for that activity
distance_by_activity JSON Distance traveled, in meters, split by activity type. In the JSON, each key is an activity type and the value is the distance traveled during that activity
steps_by_activity JSON Steps traveled, in meters, split by activity type. In the JSON, each key is an activity type and the value is the steps traveled during that activity. Returned only for walk, run and stop activities
confidence String Confidence in distance traveled computation. Possible values are high and low
confidence_reason String Reason for low confidence in distance traveled computation. If confidence is high, this is empty string

Here are the properties of duration_by_activity, distance_by_activity, and steps_by_activity JSON:

Property Type Description
total Integer Total distance/duration
drive Integer Distance/duration for which user was driving
cycle Integer Distance/duration for which user was cycling
walk Integer Distance/duration/steps for which user was walking
run Integer Distance/duration/steps for which user was running
stop Integer Distance/duration/steps for which user was stopped
unknown_location_disabled Integer Duration for which user had turned off location on the device
unknown_location_permission_denied Integer Duration for which user had denied location permission to your app
unknown_activity_permission_denied Integer Duration for which user had denied Motion and Fitness permission to your app (applicable only on iOS devices)
unknown_sdk_killed Integer Duration for which the HyperTrack SDK was killed on user's device
unknown_device_off Integer Duration for which user's device was switched off (available only for Android devices)
unknown_tracking_paused Integer Duration for which the user's device was not being tracked as pauseTracking() had been called
Sample response JSON
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "ce2102c3-b411-4481-b13e-87559f2b441f",
            <!-- all user properties -->

            "min_recorded_at":"",
            "max_recorded_at":"",
            "action_count":"3",

            "duration_by_activity": {
                "total": 1646,
                "drive": 1600,
                "cycle": 0,
                "run": 0,
                "walk": 0,
                "stop": 46,
                "unknown_location_disabled": 0,
                "unknown_location_permission_denied": 0,
                "unknown_activity_permission_denied": 0,                
                "unknown_sdk_killed": 0,
                "unknown_device_off": 0,
                "unknown_tracking_paused": 0,
            },

            "distance_by_activity": {
                "total": 120,
                "drive": 100,
                "cycle": 0,
                "run": 15,
                "walk": 5,
                "stop": 0,
            },

            "steps_by_activity": {
                "total": 200,
                "run": 10,
                "walk": 40,
                "stop": 150,
            },

            "confidence": "high",
            "confidence_reason": "",
        },

        {
            "id": "00003703-e65f-49bf-a76f-f73727afbb86",
            <!-- all user properties -->

            "min_recorded_at":"",
            "max_recorded_at":"",
            "action_count":"5",

            "duration_by_activity": {
                "total": 1746,
                "drive": 1400,
                "cycle": 0,
                "run": 0,
                "walk": 0,
                "stop": 46,
                "unknown_location_disabled": 300,
                "unknown_location_permission_denied": 0,
                "unknown_activity_permission_denied": 0,                
                "unknown_sdk_killed": 0,
                "unknown_device_off": 0,
                "unknown_tracking_paused": 0,
            },

            "distance_by_activity": {
                "total": 120,
                "drive": 100,
                "cycle": 0,
                "run": 0,
                "walk": 20,
                "stop": 0,
            },

            "steps_by_activity": {
                "total": 200,
                "run": 10,
                "walk": 40,
                "stop": 150,
            },

            "confidence": "low",
            "confidence_reason": "distance may be inaccurate as user location was disabled for long",

        }
    ]
}

Placeline

Get placeline of actions of a user, in a given time range.

HTTP Request

GET https://api.hypertrack.com/api/v2/users/<id>/placeline/

Parameters

You can pass paramters min_recorded_at and max_recorded_at to get placeline of the user between those timestamps. If you pass neither then placeline for that calendar date as per your account timezone is returned.

Parameter Type Description
min_recorded_at ISO datetime string The date/time from which you want the placeline
max_recorded_at ISO datetime string The date/time to which you want the placeline
Sample API Request
curl -H "Authorization: token SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/users/<id>/placeline/
```

{% sample lang="node" %}
```javascript
```

{% sample lang="ruby" %}
```ruby
Returns

Returns an object which contains:

  • user object and
  • placeline JSON: It is a list of activity segments, where each segment is defined by a start and an end timestamp, and has relevant location and health data as properties. Examples of activity types are stop, walk, and drive.
  • activity_summary JSON: It describes duration, distance traveled and steps moved by the user, split by activity type.
  • actions JSON: It is a list of action objects, one for each action that was pending on the user in the given time range.
  • events JSON: It is a list of event objects, one for each event generated by hypertrack in given time range. See list of events that are generated for a user.
Sample API Response
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "00003703-e65f-49bf-a76f-f73727afbb86",
            <!-- all user properties -->

            <!-- placeline -->
            "placeline": [
                {
                  # segment identifiers
                  "id": "5c7a0e2e-35ce-4482-baa3-34f837146071",
                  "started_at": "2017-07-13T00:05:22.757000+00:00",
                  "duration": 95738.982,

                  # derived from activity
                  "type": "walk",
                  "step_count": 301,

                  # derived from location
                  "distance": 310.473,
                  "route": "aiseFr_ajVAA??fA{A??LO??l@t@??r@bA??PT??HL??r@`A??`CcD",
                  "location_time_series": "aiseFr_ajVcs{ykx@bA????PT????HL????r@`A????`CcDA",

                  # derived from device health
                  "health": [
                    {
                      "type": "network_offline",
                      "recorded_at": "2017-07-14T02:41:02.046000Z",

                    },
                    {
                      "type": "battery_low",
                      "recorded_at": "2017-07-14T02:42:01.046000Z"
                    }
                  ]
                },

                {
                  # segment identifiers
                  "id": "5c7a0e2e-35ce-4482-baa3-34f837146071",
                  "started_at": "2017-07-13T00:05:22.757000+00:00",
                  "duration": 95738.982,

                  # derived from activity - for a stop
                  "type": "stop",
                  "step_count": 301,

                  # derived from location - for a stop
                  "place": {
                    "id": "83f46d89-cacd-4a1a-9007-507dbd5a4d7c",
                    "geojson": {
                      "type": "Point",
                      "coordinates": [
                        -122.3985203814826,
                        37.7869638230917
                      ]
                    },
                    "name": "Rincon Hill Apartments",
                    "address": "182 2nd St, San Francisco, CA 94105, USA",
                    "locality": "South Beach",
                    "landmark": "",
                    "zip_code": "94105",
                    "city": "SF",
                    "state": "CA",
                    "country": "US"
                  },

                  # derived from device health
                  "health": []
                },

                {
                  # segment identifiers
                  "id": "5c7a0e2e-35ce-4482-baa3-31499904322",
                  "started_at": "2017-07-13T00:05:22.757000+00:00",
                  "duration": 95738.982,

                  # derived from activity - for unknown activity
                  "type": "unknown",
                  "unknown_reason": "activity_permission_denied",

                  # derived from location
                  "distance": 310.47333797811655,
                  "route": "LO??l@t@??r@bA??PT??HL??r@`A??`CcD",
                  "location_time_series": "{ykx@bA????PT????HL????r@`A????`CcDA",

                  # derived from device health
                  "health": [],
                }
            ]
        }
    ]
}

Filtering and ordering parameters

You can pass the following parameters as arguments in the URL of users GET API that returns a list. The list can be filtered/ordered using one or more parameters. All of them are optional.

Identifier filters
Parameter Type Description
id UUID String Filter user that has this id. To filter multiple users, use a comma separated list of ids
unique_id String Filter user that has this unique_id. To filter multiple users, use a comma separated list of unique_ids
group_id String Filter users that have this group_id. To filter users from multiple groups, use a comma separated list of group_ids
name String Filter users with name that contains this string. You can pass a comma separated list of names.

Here is a sample API to get list of actions filtered by ids:

curl -H "Authorization: token SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/users/?id=41caa9f2-ad63-4a8b-98ed-1414c372e1ce,4e2a8344-9864-4473-864f-e223dec208b3
Datetime filters
Parameter Type Description
min_last_heartbeat_at ISO datetime string Filter users whose last_heartbeat_at is after this datetime
max_last_heartbeat_at ISO datetime string Filter users whose last_heartbeat_at is before this datetime

Here is a sample API to get list of users filtered by last_heartbeat_at dates:

curl -H "Authorization: token SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/users/?min_last_heartbeat_at=2017-10-24T18%3A30%3A00.000Z&max_last_heartbeat_at=2017-10-25T18%3A29%3A59.999Z
Location filters

Tell us if you need this API, we will prioritise its development

Parameter Type Description
last_location__bbox Comma separated 4-tuple of lat and long Filter users within a bounding box. Specified as max_lng,max_lat,min_lng,min_lat
Activity filters

Tell us if you need this API, we will prioritise its development

Parameter Type Description
activity String Filter users that have this activity. You can pass a comma separated list of activities.
Device health filters

Tell us if you need this API, we will prioritise its development

Parameter Type Description
location_status String Filters users that have this location_status. Learn more.
network_status String Filters users that have this network_status. Learn more.
battery_status String Filters users that have this battery_status. Learn more.
Pagination parameter
Parameter Type Description
page_size integer Maximum number of objects to return, default is 50
Ordering parameter

You can order the objects returned in response of any GET list API by adding the optional ordering parameter to the URL. This parameter can have one of the following possible values. By default, the ordering is done in ascending order for the specified value. Prefix a - (minus) sign to any of the below values to get descending order.

  • Datetime ordering values: created_at, or last_heartbeat_at.
  • Identifier ordering values: unique_id, group_id, or name, ordered lexicographically.
  • Device health ordering values: location_status, network_status or battery_status, ordered lexicographically. Tell us if you need this API, we will prioritise its development

Here is a sample to get list of users ordered by the most recent heartbeat:

curl -H "Authorization: token SECRET_KEY" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/users/?ordering=-last_heartbeat_at

results matching ""

    No results matching ""