User

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

User objects can belong to a Group object. User objects can be assigned Action objects.

User object's properties

Property Type Description
id UUID string Unique identifier for the object
name string Name of the user
phone string E164 formatted phone number of user
group_id UUID string The id of the fleet to which this user belongs
lookup_id string A unique id that you can add to the user to identify
availability_status string The availability status of the user, possible values are online, offline. Details here
location_status string The location status of the user, possible values are location_available, location_disabled, location_permission_disabled and location_low_accuracy. Details here
is_connected boolean Flag denoting the connection status of the user, possible values are true and false. Details here
last_location JSON The last known location of the user with the speed, bearing, location accuracy and recorded time fields. Location object spec
last_heartbeat_at datetime Date time for last communication with the user's device
last_online_at datetime Date time when the last tracking session was started for the user
last_battery integer Battery percentage that was last recorded for the user
segments JSON array This the Placeline of the user i.e. a list of activity segments with location and other imp data points. Read this for more details
pending_actions UUID array List of action ids that have been assigned to the user and are not complete
created_at datetime Timestamp of when user was created
modified_at datetime Timestamp of when user was last modified

Availability status

Availability status Description
online When the user's session has been started with startTracking on the SDK
offline When the user's session has been ended by stopTracking on the SDK

Location status

Location status Description
location_available When user location is available from the SDK
location_disabled When user has turned off location on his/her device
location_permission_disabled When user has denied location permission to your app
location_low_accuracy When user has denied location at high accuracy, or when user's device doesn't have high accuracy GPS

Connection status

Connection status Description
true When the device has network connectivity with the HyperTrack server
false When the device has lost network connectivity with the HyperTrack server

API calls

Base url: https://api.hypertrack.com/api/v1/

API call Method URL Description
Create a user users/ Create a new user object
Retrieve a user users/ID/ Get an existing user object
Retrieve multiple users users/ Get multiple user objects, filtered by given params
Update a user users/ID/ Update an existing user object
Delete a user users/ID/ Delete an existing user object
Delete all users users/delete_all/ Delete all user objects (works only for test environment)
Retrieve nearby users users/nearby/ List all users near a given location
Assign actions to a user users/ID/assign_actions/ Assign actions to a user
Cancel actions of a user users/ID/cancel_actions/ Cancels all actions that have been assigned to that user
Complete actions of a user users/ID/complete_actions/ Completes all actions that have been assigned to that user
Meter users users/meter_actions/ For all users, meters the actions that have been completed by the user in a given time range
Stop tracking a user users/ID/stop_tracking/ Stop tracking the user
Stop tracking for multiple users users/bulk_stop_tracking/ Stop tracking a list of users
Retrieve analytics data users/analytics/ Retrieve user data aggregated between two timestamps

CRUD APIs

Create a User

This API will create and return a User object.

HTTP Request

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

Returns

Returns a user object if the call succeeded.

Parameters
Parameter Required Description
name No Name of the user
phone No E164 formatted phone number of the user
photo No A photo file of the user
lookup_id No A unique id that you can add to the user to search
group_id No The identifier of the group to which the user belongs

[warning] Lookup id behavior

If User with a given lookup_id already exists, then the existing user will be returned instead of creating a new one.

curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"name\": \"User name\", \"phone\": \"+16502469293\"}" \
     https://api.hypertrack.com/api/v1/users/
hypertrack.User.create(
    name='Steve Smith',
    phone='+16502469293'
)
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
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'
})

Retrieve a User

Retrieves a user object with the id.

HTTP Request

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

Returns

Returns a user object if a valid identifier was provided.

curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
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) {})

Update a User

Edit an existing user object.

HTTP Request

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

Returns

Returns the updated user object.

Parameters
Parameter Required Description
name No Name of the user
phone No E164 formatted phone number of the user
photo No URL of the photo to be assigned to the user
lookup_id No A unique id that you can add to the user to search
group_id No The identifier of the group to which the user belongs
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"name\": \"User name\", \"phone\": \"+16502469293\"}" \
     https://api.hypertrack.com/api/v1/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("YOUR_SK_TOKEN");
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"
        }
    );

Delete a User

Delete an existing user object.

HTTP Request

DELETE https://api.hypertrack.com/api/v1/users/<id>/

Returns

Empty response if the object is deleted.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X DELETE \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
user.delete()
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");
userFactory.delete(user);
hypertrack.user
    .remove("d0ae4912-2074-45ef-a7c0-76be58639ea9");

Retrieve multiple users

List all user objects. The list can be filtered using the following parameters.

HTTP Request

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

Returns

Returns a list of users.

Parameters

You can pass any of the user filter parameters to filter users. You will find the filters on properties id, lookup_id, group_id and last_location__bbox particularly useful.

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

Delete all Users in test environment

Delete all users, if its in test environment. If it is in production then all users cannot be deleted in a single API call. The API has no paramters and returns status 200 if successful.

HTTP Request

DELETE https://api.hypertrack.com/api/v1/users/bulk_delete/

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X DELETE \
     https://api.hypertrack.com/api/v1/users/bulk_delete/

Utility APIs

List nearby Users

List all users near a given location ([latitude,longitude] or an action's expected_place). The users are returned in the order of their distance to the location of interest. This API can be used to find the best user to be assigned to an action.

HTTP Request

GET https://api.hypertrack.com/api/v1/users/nearby/

Returns

Returns a list of users, in the order of distance to the location.

Parameters
Parameter Required Description
action_id One of action_id or location is required Action id to get nearby users from that action's expected place
location One of action_id or location is required longitude,latitude to get nearby users from that location
radius No Restricts the results to all users within this radius (specified in meters) of the location

Additionally, you can pass any of the user filter parameters to filter users. You will find the filters on properties id, lookup_id and group_id particularly useful.

Samples

# Nearby with action_id
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/nearby/?action_id=ACTION_ID

# Nearby with action_id & radius
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/nearby/?action_id=ACTION_ID&radius=RADIUS_IN_METERS

# Nearby with location and restrict result to set of Users ids.
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/nearby/?location=longitude,latitude&id=user_id_1,user_id_2,...

Assign Actions to a User

This API will assign a list of Action objects to a User.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/<id>/assign_actions/

Returns

Returns a User object to which the actions are added.

Parameters
Parameter Required Description
action_ids Yes List of action ids to be assigned to the user
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"action_ids\": [\"6daacb03-6f02-4c60-b084-e9ffcd9eaf56\", \"37ae09b4-4801-48cb-bc50-99a7ee53f257\"]}" \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/assign_actions/
user = hypertrack.User.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
user.assign_actions(action_ids=['6daacb03-6f02-4c60-b084-e9ffcd9eaf56', '37ae09b4-4801-48cb-bc50-99a7ee53f257'])
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
UserFactory userFactory = new UserFactory(client);
User user = userFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");

List<String> actionIds = Arrays.asList("6daacb03-6f02-4c60-b084-e9ffcd9eaf56", "37ae09b4-4801-48cb-bc50-99a7ee53f257");
userFactory.assignActions(user, actionIds);
user = HyperTrack::User.retrieve(user_id)
user.assign_actions({action_ids: ['6daacb03-6f02-4c60-b084-e9ffcd9eaf56', '37ae09b4-4801-48cb-bc50-99a7ee53f257']})
hypertrack.user
    .assignAction(
        "d0ae4912-2074-45ef-a7c0-76be58639ea9",
        {
            "action_ids": [
                "6daacb03-6f02-4c60-b084-e9ffcd9eaf56",
                "37ae09b4-4801-48cb-bc50-99a7ee53f257"
            ]
        }
    );

Cancel actions of a user

This API will cancel all actions have been assigned to a User.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/<user-id>/cancel_actions/

Returns

Returns a user object if the call succeeded.

curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/<user-id>/cancel_actions/

Complete actions of a user

This API will complete all actions have been assigned to a User.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/<user-id>/complete_actions/

Returns

Returns a user object if the call succeeded.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/<user-id>/complete_actions/

Meter users

This API will meter all actions that were completed by user between two given timestamps. This API returns meter data for all the users of your account. You can get this data in JSON as well as CSV format.

Parameters

There are two required timestamp parameters.

Parameter Type Required
min_time ISO datetime Yes
max_time ISO datetime Yes
HTTP Request

GET https://api.hypertrack.com/api/v1/users/meter_actions/

Sample code to meter all the users of your account on 30th Jan 2018 (UTC), and get the data in CSV format

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Accept: text/csv" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/meter_actions?min_time=2018-01-30T00:00:00Z&max_time=2018-01-31T00:00:00Z
Returns

Returns a list of objects. Each object corresponds to a user. Each object has the following properties.

Property Type Description
id UUID string Unique identifier of the user
min_time ISO datetime Parameter passed in request
max_time ISO datetime Parameter passed in request
action_count integer Number of actions that were completed by the user between the two timestamps passed as paramters
distance integer Distance traveled in metres, by user between the time that the first action was completed by user and the time that the last action was completed
duration integer Time difference in seconds, between the time that the first action was completed by user and the time that the last action was completed
shortest_distance integer Distance in metres, of the shortest path between the completed_places of all the actions that were completed within given time range
comment text If there is an unexpected value in any of the above properties, its mentioned in this property. Eg, Shortest distance is lesser than expected because completed place of 1 actions could not be saved
Examples

Say 4 actions are assigned to a user. action #1 is completed at 02:30hrs, #2 is completed at 03:30hrs, #3 is completed at 04:30hrs, #4 is completed at 05:30hrs.

  • If min_time is passed as 02:00hrs and max_time as 06:00hrs, distance returned by this API will be the distance travelled between 02:30hrs and 05:30hrs.
  • If min_time is passed as 03:00hrs and max_time as 05:00hrs, distance returned by this API will be the distance travelled between 03:30hrs and 04:30hrs.
  • If min_time is passed as 02:00hrs and max_time as 03:00hrs, this API will return distance 0 as only one action was completed in this period. If 0 or 1 action was completed by the user in given time range, then 0 value is returned for distance, duration and shortest_distance properties, as they can be calculated only when there are atleast two locations/timestamps.

Stop tracking user

You can use this API to call stop tracking from the backend. This requires a network connection on the device. Data recorded after the point when stop tracking is called will be ignored.

Condition Result
Push configured and network is available SDK will stop tracking
Push configured and network is unavailable SDK will stop tracking when the network comes back up
Push not configured SDK will stop tracking when it is makes a network call to the server
HTTP Request

POST https://api.hypertrack.com/api/v1/users/USER_ID/stop_tracking/

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/USER_ID/stop_tracking/

Stop tracking for multiple users

You can use this API to call stop tracking from the backend. This requires a network connection on the device. Data recorded after the point when stop tracking is called will be ignored.

Condition Result
Push configured and network is available SDK will stop tracking
Push configured and network is unavailable SDK will stop tracking when the network comes back up
Push not configured SDK will stop tracking when it is makes a network call to the server
HTTP Request

POST https://api.hypertrack.com/api/v1/users/bulk_stop_tracking/

Request body
Parameters Description
user_ids List of user uuids. If not specified, then all users on the account stop tracking
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/users/bulk_stop_tracking/

Analytics APIs

Retrieve analytics data

You can use this API to get user data like distance travelled, duration of being tracked, duration for which location was disabled and so on, aggregated between two timestamps, for a user. You can get this data for one user or multiple users by using the filter parameters specified below.

HTTP Request

POST https://api.hypertrack.com/api/v1/users/analytics/

Returns

Returns a list of user analytics objects. Each object has the following properties, which are aggregates calculated for the duration correspondging to the timestamp filters.

Property Type Description
id UUID string Unique identifier for the object
num_places integer Total number of places where the the user stopped
num_actions integer Total number of actions assigned to the user
total_distance float Total distance covered by the user
total_duration float Total duration for which the user was tracked. It is the total duration for which the user's availability_status property was online
stop_duration float Total duration for which the user was at a stop
location_disabled_duration float Total duration for which user has turned off location on the device or has denied location permission to your app. It is the total duration for which the user's location_status property was location_disabled or location_permission_disabled
network_offline_duration float Total duration for which the user's device had lost network connectivity. It is the total duration for which the user's is_connected property was false
Parameters

You can pass the following additional filter parameters as arguments in the URL, besides the user filter parameters.

Parameter Type Required Description
min_recorded_at ISO datetime No Calculate aggregates using user data starting from this timestamp. Default is since account was created
max_recorded_at ISO datetime No Calculate aggregates using user data till this timestamp. Default is current time
show_all boolean No Set to true to return data for all users ever created in the account. Default is false
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/analytics?id=USER_ID_1,USER_ID_2&min_recorded_at=2017-10-24T18%3A30%3A00.000Z&max_recorded_at=2017-10-25T18%3A29%3A59.999Z
Ordering

You can pass the ordering parameter with any of the possible user ordering values. Additionally, you can use any of the properties returned in the user analytics object like num_actions, total_distance, location_disabled_duration and so on. By default, the ordering is ascending. Prefix a - (minus) sign to a value to get descending order by that property.

Sample to get analytics data of all users for the month of January 2018, ordered such that the users with the highest duration of location disabled show first

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users/analytics?min_recorded_at=2018-01-01T00%3A00%3A00.000Z&max_recorded_at=2018-01-31T00%3A00%3A59.999Z&ordering=-location_disabled_duration

Filter parameters

You can pass the following parameters as arguments in the URL of any GET list API. All of the parameters are optional. You will find them particularly useful in APIs to retrieve multiple actions, list nearby users and retreive analytics data.

Datetime filters

Parameter Type Description
min_last_online_at ISO datetime Filter users whose availability_status was last online after this datetime
min_last_online_at ISO datetime Filter users whose availability_status was last online before this datetime
min_last_heartbeat_at ISO datetime Filter users whose last_heartbeat_at is after this datetime
max_last_heartbeat_at ISO datetime Filter users whose last_heartbeat_at is before this datetime

Sample to get list of all active users in the month of January 2018.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/users?min_last_heartbeat_at=2018-01-01T00%3A00%3A00.000Z&min_last_heartbeat_at=2018-01-31T00%3A00%3A59.999Z

State filters

Parameter Type Description
availability_status string Filter users that have this availability_status. To specify multiple statuses, use a comma separated list
location_status string Filter users that have this location_status. To specify multiple statuses, use a comma separated list
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

Identifier filters

Parameter Type Description
id UUID String Filter user that has this id. For multiple users, use a comma separated list of ids
group_id UUID String Filter users that have this group_id. For multiple groups, use a comma separated list of ids
lookup_id string Filter users that have this lookup_id. For multiple users, use a comma separated list of ids
name string Filter users with name that contain this string

Pagination parameter

Parameter Type Description
page_size integer Maximum number of objects to return, default is 50

Ordering paramter

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

Value Description
created_at Order users by created_at
last_heartbeat_at Order users by last_heartbeat_at
last_online_at Order users by last_online_at

Sample to get list of users ordered by the most recently updated first

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

Identifier ordering values

Value Description
lookup_id Order by lookup_id, lexicographically
group_id Order by group_id. Useful if you want to group users by group
name Order by name, lexicographically

State ordering values

Useful if you want to group users by status.

Value Description
availability_status Order by availability_status, lexicographically
location_status Order by location_status, lexicographically
last_battery Order by last_battery percentage

results matching ""

    No results matching ""