Action

Actions are the key building blocks for your use cases. Use actions to build tracking experience, get ETAs and status, get geofencing alerts, or just annotate actions that take place in your app.

Introduction

Post key actions performed by users in your app as actions in the HyperTrack API.

For instance, apps for work want to track pickups, deliveries and appointments; and apps for consumers want to track meetups, visits and payments. Actions can be anything you want to track with HyperTrack.

Action Object

Identifiers

Property Type Description
id uuid string Unique identifier for the action object created by HyperTrack
unique_id string Unique identifier for the action object provided by you; can be based on your internal id
type string Type of action, e.g., pickup, delivery, dropoff, visit, stopover, task
collection_id string Identifier provided by you to club and sequence actions; can be based on your internal id
user JSON User object to which the action is assigned
tracking_url string URL at which this action can be tracked. This URL can be shared with anyone

Current State

Property Type Description
eta ISO datetime string Current ETA for the action, calculated in real-time. It is calculated if expected_place is set for the action
initial_eta ISO datetime string Initial ETA calculated for the action
status string Current action status. Can be in_queue, leaving_now, on_the_way, arriving, arrived, completed, and canceled
distance_covered float Distance covered by user (in meters) from assigned_at time to current time (completed_at or canceled_at time for completed/canceled actions)
distance_remaining float Distance remaining (in meters) to the expected location of the action; will be NULL if the action is completed or canceled
time_aware_polyline string Compressed string that captures the locations and timestamps of the user from assigned_at time to current time (completed_at or canceled_at time for completed/canceled actions)
encoded_polyline string Compressed string (based on Google's encoded polyline format) that captures the locations of the user from assigned_at time to current time (completed_at or canceled_at time for completed/canceled actions)
encoded_polyline_remaining string Compressed string (based on Google's encoded polyline format) that captures the expected locations of the user from current location to expected location of the action; will be NULL if the action is completed or canceled

Archived State

Property Type Description
created_at ISO datetime string Timestamp at which the action was created
created_place JSON Place where the user was when the action was created
expected_at ISO datetime string Time by when the action is expected to be completed. It is used to calculate if an action is delayed
expected_place JSON Place where the action is expected to be completed. It is used to calculate eta of an action
completed_at ISO datetime string Time at which the action was completed
completed_place JSON Place where the action was completed
canceled_at ISO datetime string Time at which the action was canceled, if it was canceled
canceled_place JSON Place where the action was canceled, if it was canceled
modified_at ISO datetime string Timestamp at which the action was last modified

Metadata

Property Type Description
metadata JSON Custom key-values that can be specified by you to view the action details; e.g., customer name, customer phone number

Action Collections

In scenarios where you need ETA for nth action in queue, use Collections to club & queue actions. E.g.,

  • An order in your system can represent one pickup and one delivery on our API
  • A milk run in your system can represent multiple delivery actions on our API

These collections can be represented via the collection_id property of the action object. While creating these actions, specify the collection_id to be the internal identifier that you have for the collection (eg, order id or milk run id in the above examples).

The collection_id is different from the unique_id.

  • collection_id represents action collections. Therefore, multiple actions can have the same collection identifier.
  • unique_id uniquely identifies an action. Therefore, multiple actions cannot have the same lookup identifier.

API calls

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

API call Method URL Description
Create an action actions/ Creates and assigns a new action object
Assign action(s) to a user user/ID/assign_actions/ Assigns a list of action objects to a user
Update an action actions/ID/ Edit an existing action object
Retrieve an action actions/ID/ Retrieves an existing action object
Delete an action actions/ID/ Deletes an existing action object
Complete an action actions/ID/complete Completes an existing action object
Cancel an action actions/ID/cancel Cancels an existing action object
Meter an action actions/ID/meter Returns distance and duration traveled for the action, since the action was assigned to the user
List all actions actions/ Lists all actions objects, filtered based on parameters specified
Retrieve analytics data actions/analytics Lists all actions objects, filtered based on parameters specified, alongwith analytics data

Create Action

Creates a new action object. Pass the user_id in the parameter if you want to assigns it to a user. Pass completed as the status in the parameter if this action took place already and you want to just annotate it on user's placeline.

HTTP Request

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

Parameters
Parameter Required Comment
expected_place No Only one of expected_place or expected_place_id must be specified
expected_place_id No Use this parameter instead of expected_place if your users are going to perform actions at a place very frequently. So instead of sending address (in a Place object) every time you create an action, you can (1) create a Place one time, (2) store the id of the Place object you get in response, and (3) send this id every time you create an action
expected_at No -
type No Defaults to task if no type is specified
unique_id No -
collection_id No -
user_id No You can specify user_id if you already know the user who is going to perform this action. If not, you can create an Action without an User ID, and later assign action to a user
status No Leave it blank if the action is expected to take place in the future. Mark it completed if this action took place already and you want to just annotate it on user's placeline
metadata No -
Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"expected_place\": {\"address\": \"2200 Sand Hill Road Menlo Park CA USA\"}, \"scheduled_at\": \"2016-03-09T07:00:00.00Z\"}" \
     https://api.hypertrack.com/api/v1/actions/
place = {'address': "2200 Sand Hill Road Menlo Park CA USA"}
hypertrack.Action.create(
    expected_place=place,
    scheduled_at='2016-03-09T07:00:00.00Z'
)
place = {
    'address': "2200 Sand Hill Road Menlo Park CA USA"
}
hypertrack.action.create({
    "expected_place": place,
    "scheduled_at":"2016-03-09T07:00:00.00Z"
});
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Map<String, Object> place = new HashMap<>();
place.put("address", "2200 Sand Hill Road Menlo Park CA USA")
Map<String, Object> params = new HashMap<>();
params.put("expected_place", place);
params.put("scheduled_at", "2016-03-09T07:00:00.00Z");
Action action = actionFactory.create(params);
place = Hash.new()
place['address'] = '2200 Sand Hill Road Menlo Park CA USA'
HyperTrack::Action.create(expected_place: place,
                          scheduled_at: '2016-03-09T07:00:00.00Z')
Returns

Returns an action object if the call succeeded.

Sample API Response


Assign Actions to a User

Assign a list of Action objects to a user.

HTTP Request

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

Parameters
Parameter Required Description
action_ids Yes List of action ids to be assigned to the user
Sample API Request
curl -H "Authorization: token YOUR_SK_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'])
hypertrack.user.assignAction(
    "d0ae4912-2074-45ef-a7c0-76be58639ea9",
    {"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']})
Returns

Returns a user object to which the actions are added.

Sample API Response


Update Action

Edit an existing action object. You can use this API to assign an action to a user (if you had previously created this action without an user_id), change the expected_place of the action, or any other parameter of the action.

HTTP Request

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

Parameters
Parameter Required Comment
expected_place No Only one of expected_place or expected_place_id must be specified
expected_place_id No Only one of expected_place or expected_place_id must be specified
expected_at No -
type No -
unique_id No -
collection_id No -
user_id No Use this API call and specify user_id assign action to a user
metadata No -
Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"type\": \"pickup\", \"lookup_id\": \"CRN1234\"}" \
     https://api.hypertrack.com/api/v1/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
action = hypertrack.Action.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
action.type = 'pickup'
action.lookup_id = 'CRN1234'
action.save()
hypertrack.action
    .update(
        "d0ae4912-2074-45ef-a7c0-76be58639ea9",
        {
            "type": "pickup",
            "lookup_id": "CRN1234"
        }
    );
Returns

Returns the updated action object.

Sample API Response


Retrieve Action

Retrieves an action object with the id.

HTTP Request

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

Sample API Request
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/ce2102c3-b411-4481-b13e-87559f2b441f/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
hypertrack.action
    .retrieve("ce2102c3-b411-4481-b13e-87559f2b441f")
    .then(function(action) {})
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
HyperTrack::Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
Returns

Returns an action object if the call succeeded.

Sample API Response


Delete Action

Delete an existing action object.

HTTP Request

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

Parameters

No parameter available.

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X DELETE \
     https://api.hypertrack.com/api/v1/actions/f3ead2ae-dc0a-4a7e-85be-74ee51d9d70a/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.delete()
hypertrack.action
    .remove("ce2102c3-b411-4481-b13e-87559f2b441f");
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
actionFactory.delete(action);
Returns

Empty response if the object is deleted.

Sample API Response


Complete Action

Completes an existing action object.

[warning] Completing actions

If marking actions is done using interactions in the mobile app, we recommend using the SDK methods to complete actions. This ensures that the action has the right metadata for more accurate data collection.

HTTP Request

POST https://api.hypertrack.com/api/v1/actions/<id>/complete/

Parameters
Parameter Required Comment
completed_at No Defaults to the timestamp complete action API is called; you can override it with a different timestamp if at all required
Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/actions/ce2102c3-b411-4481-b13e-87559f2b441f/complete/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.complete()
hypertrack.action
    .complete("ce2102c3-b411-4481-b13e-87559f2b441f");
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
actionFactory.complete(action, null);
action = HyperTrack::Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.complete()
Returns

Returns an action object if the call succeeded.

Sample API Response


Cancel Action

Cancels an Action. Canceled actions cannot be updated, reassigned, or completed.

HTTP Request

POST https://api.hypertrack.com/api/v1/actions/<id>/cancel/

Parameters

No parameters available.

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v1/actions/ce2102c3-b411-4481-b13e-87559f2b441f/cancel/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.cancel()
hypertrack.action
    .cancel('ce2102c3-b411-4481-b13e-87559f2b441f');
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
actionFactory.cancel(action, null);
action = HyperTrack::Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.cancel()
Returns

Returns an action object if the call succeeded.

Sample API Response


Meter Action

Returns distance and duration traveled for the action, since the action was created and assigned to the user.

HTTP Request

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

curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/ce2102c3-b411-4481-b13e-87559f2b441f/meter/
action = hypertrack.Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.meter()
hypertrack.action
    .meter("ce2102c3-b411-4481-b13e-87559f2b441f")
    .then(function(meter) {});
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
ActionFactory actionFactory = new ActionFactory(client);
Action action = actionFactory.retrieve("ce2102c3-b411-4481-b13e-87559f2b441f");
actionFactory.meter(action, null);
action = HyperTrack::Action.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
action.meter()
Returns

Returns an object with distance and duration fields, if the call succeeded.

Sample API Response


List all Actions

Lists all actions objects. The list can be filtered using the one or more parameters.

HTTP Request

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

Parameters
Parameter Type Required Description
page_size No Maximum number of objects to return; default is 50
min_created_at ISO datetime No Filter actions which were created after this datetime
max_created_at ISO datetime No Filter actions which were created before this datetime
min_assigned_at ISO datetime No Filter actions which were assigned after this datetime
max_assigned_at ISO datetime No Filter actions which were assigned before this datetime
min_completed_at ISO datetime No Filter actions which were completed after this datetime
max_completed_at ISO datetime No Filter actions which were completed before this datetime
id UUID String No Filter action that has this id. To get analytics on multiple actions, use a comma separated list of ids
collection_id string No Filter actions that have a collection_id that contains this string
unique_id string No Filter actions that have a unique_id that contains this string. To get analytics on multiple actions, use a comma separated list of unique ids
user_id string No Filter actions that are assigned to the specified user_id. To get analytics for actions of multiple users, use a comma separated list of user ids
group_id string No Filter actions that are assigned to users in the specified group_id
Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/?page_size=20
actions = hypertrack.Action.list()
hypertrack.action
    .list()
    .then(function(actions) {});
HyperTrack::Action.list
Returns

Returns a paginated list of user objects, with each page containing specified number of action objects.

Sample API Response


Retrieve Action Analytics

Use this API to get data like duration for which order was untrackable due to location being unavailable or network being unavailable, for each action. Get this data for one or more actions by using the filter parameters specified below.

HTTP Request

GET https://api.hypertrack.com/api/v1/actions/analytics/

Parameters
Parameter Type Required Description
page_size No Maximum number of objects to return; default is 50
min_created_at ISO datetime No Filter actions which were created after this datetime
max_created_at ISO datetime No Filter actions which were created before this datetime
min_assigned_at ISO datetime No Filter actions which were assigned after this datetime
max_assigned_at ISO datetime No Filter actions which were assigned before this datetime
min_completed_at ISO datetime No Filter actions which were completed after this datetime
max_completed_at ISO datetime No Filter actions which were completed before this datetime
id UUID String No Filter action that has this id. To get analytics on multiple actions, use a comma separated list of ids
collection_id string No Filter actions that have a collection_id that contains this string
unique_id string No Filter actions that have a unique_id that contains this string. To get analytics on multiple actions, use a comma separated list of unique ids
user_id string No Filter actions that are assigned to the specified user_id. To get analytics for actions of multiple users, use a comma separated list of user ids
group_id string No Filter actions that are assigned to users in the specified group_id
Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/analytics?min_created_at=2017-10-24T18%3A30%3A00.000Z&max_created_at=2017-10-25T18%3A29%3A59.999Z
Returns

Returns a paginated list of user analytics objects, with each page containing 50 objects. Each object has the following properties.

Property Type Description
id UUID string Unique identifier for the action
duration float Time difference, in seconds, between when action was assigned to the user and when it was completed or canceled
location_disabled_duration float Duration (in seconds) 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 Duration (in seconds) 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
untrackable_duration float Duration (in seconds) for which the user's device had lost network connectivity or user turned off location on the device or has denied location permission to your app. Think of it as the union of location_disabled_duration and network_offline_duration
Sample API Response
{
    "count": 61,
    "next": "https://api.hypertrack.com/api/v1/actions/analytics/?page=2",
    "previous": null,
    "results": [
        {
            "id": "00003703-e65f-49bf-a76f-f73727afbb86",
            "duration": 1746,
            "untrackable_duration": 0,
            "location_disabled_duration": 0,
            "network_offline_duration": 0
        },
        {
            "id": "00003a08-6096-4fb8-b1d7-bb2c848c06cd",
            "duration": 2147,
            "untrackable_duration": 91.574,
            "location_disabled_duration": 0,
            "network_offline_duration": 91.574
        },
        ...
    ]
}

Using Actions

You can program actions both from your backend and mobile app. If your backend is the source-of-truth for the actions, create and update Actions from your backend. If your app has all the latest details of the Actions, create and update actions using the SDK methods.

Actions is one the core building blocks for building live location features in your app. Here are few common scenarios when you can use Actions to build your product:

Below, we outline how you would program action for above scenarios. Note that in each of the scenarios, we assume that you have already setup the SDK in your user app, and have started tracking your user.

Tracking experience for an action

Let's say you have an action that is going to be performed by your user, e.g., a pickup, a delivery, a visit, etc. And you want to build a realtime tracking experience for that action on map. Just follow the below four steps.

  1. Create an action with expected place and user
  2. In case you didn't know about the user who is going to perform the action while creating the action, do a patch on action to assign that action to a user
  3. Track the action using the unique trck.at tracking URL that was sent in response to create-action API. You can also build your own tracking experience within your Android app, iOS app or Web app using our SDKs.
  4. Complete action on HyperTrack when you mark the action as complete in your app or server. You can alternatively cancel action, in case you canceled that action & want to sync the state on HyperTrack server as well

Realtime ETA, status, and alerts

Let's say you have an action that is going to be performed by your user, e.g., a pickup, a delivery, a visit, etc. And you want to get realtime ETAs, status (e.g., arriving, arrived, delayed), or actionable alerts (e.g., moving away from destination). Just follow the below six steps.

  1. Create an action with expected place and user
  2. In case you didn't know about the user who is going to perform the action while creating the action, do a patch on action to assign that action to a user
  3. Retrieve action to get realtime ETA and/or status for that action
  4. Call the meter action API to get current mileage for the action
  5. Setup webhooks to receive realtime alerts about the action
  6. Complete action on HyperTrack when you mark the action as complete in your app or server. You can alternatively cancel action, in case you canceled that action & want to sync the state on HyperTrack server as well

Annotate actions on user’s placeline

Let's say you want to keep marking important actions that place in your app on your user's placeline, as and when they happen. E.g., signed-up, invited a friend, made a purchase, etc. You can annotate these actions via HyperTrack and later retrieve them for analytics, audits, etc. Just follow the below two steps.

  1. Create an action. Make sure to pass user_id and state as completed in the parameter
  2. Retrieve actions to get details like location and activity of the user when an action happened in the past

Automatically create actions based on custom rules

Let's say you have a set of internal rules based on which you would want to annotate actions on your user's placeline. A typical usecase is geofencing wherein you want to receive a webhook when user visits a list of defined places. Just follow the below three steps.

  1. Set custom rule for creating actions
  2. Setup webhooks to receive realtime alerts about the actions as they happen
  3. Retrieve list of actions that took place; get a filtered list by passing one or more parameters

Get mileage & path taken between two actions

Let's say you want to measure distance travelled between two actions (e.g., a pickup action and a dropoff action). You also want to get the polyline of the path that was travelled between those two actions. Just follow the below four steps.

  1. Create an action. Make sure to pass user_id and state as completed in the parameter
  2. Create another action. Make sure to pass user_id and state as completed in the parameter
  3. Get mileage by calling meter action API and passing the above two action_ids in the parameter
  4. Get path taken by calling placeline API and passing the above two action_ids in the parameter

Get ETA of nth action in sequence

Let's say you have a set of actions that your user is going to perform (e.g., a bus driver that is going to make 10 pickup actions). You want to get ETA of each of these actions assuming the user would perform these actions in sequence. Just follow the below four steps.

  1. Create all the actions with expected place and user. Pass the same collection_id as parameter for each of these actions.
  2. The sequence of actions within a collection is automatically inferred based on the order in which you create these actions. In case you want to re-order them, ???
  3. Retrieve action to get realtime ETA and/or status for nth action
  4. Complete action on HyperTrack as and when you mark an action as complete in your app or server. You can alternatively cancel action, in case you canceled that action & want to sync the state on HyperTrack server as well.

results matching ""

    No results matching ""