Action

Actions are used to track a users while they are performing key actions in your app. They typically correspond with the key actions that your users perform in the app, viz. visit, meetup, pickup, delivery, gig, task, and so on. As such, actions can be anything you want to track with HyperTrack.

Actions are the key building blocks for your use cases. You can use actions to build tracking experience, get ETAs and status, get mileage, get geofencing alerts, or passively track a user through the day. You can

Introduction

An action can be created on hypertrack from your user's device (using the hypertrack mobile SDK) or from your server (using hypertrack REST API).

You can create multiple actions for a user, for example a pickup followed by a dropoff or a pickup followed by multiple deliveries or a visit followed by a gig. If there are multiple actions pending on a user, it is assumed that the user will complete them one by one in sequence.

Action properties

An Action object consists of following data.

1. Identifiers

These properties identify the action object.

1.1. Defined by you when creating action

Property Type Description
user JSON User object to which the action is assigned
unique_id String Unique identifier for the action object, set by you. It can be based on your internal ID
collection_id String Identifier provided by you to club and sequence actions; can be based on your internal ID
type String Type of action, e.g., pickup, delivery, dropoff, visit, stopover, task
metadata JSON Custom key-values pairs that may be useful context for your actions, specially in action visuals

1.2. Set by hypertrack when action created

Property Type Description
id UUID String Unique identifier for the action object, created by HyperTrack
tracking_url String URL at which this action can be tracked. This URL can be shared with anyone. It uses the track API

2. Actual movement properties

2.1. Defined by you when creating action

Property Type Description
is_autocomplete_at_expected_place Boolean Flag that programs hypertrack to complete the action automatically if the user arrives at the expected_place. This is useful if you don't want to depend on user input to complete the action. Default is false
is_autocomplete_at_creation Boolean Flag that programs hypertrack to create and complete the action at the same time. This is useful if you want to just annotate a point in time and location. Default is false
schedule_autocancel_at ISO datetime string Time at which you want hypertrack to automatically cancel the action, if it has not been completed till then. This is useful for garbage collection in case the action is not completed by the user. Default is 24 hours from created_at

2.2. Derived by hypertrack

2.2.1. Status
Property Type Description
status String Current status of the action. See below for possible values
updated_at ISO datetime string Time till which the action properties have been updated. It is the time that hypertrack last heard from the device corresponding to this action. Once the status changes to started hypertrack strives to keep this time as close to current time, so that you can track actions in real-time

The possible values for status are:

  • created: As soon as an action is created, its status changes to this.
  • started: If there are multiple actions pending on a user, it is assumed that the user will complete them one by one in sequence. An action's status changes to started once all actions before that (in sequence) are completed. If there are no pending actions when an action is created, its status is set to started immediately.
  • completed: As soon as an action is completed by you, its status changes to this.
  • autocompleted: If hypertrack automatically completes an action based on one of parameters defined by you when creating the action, its status changes to this.
  • canceled: As soon as an action is canceled by you, its status changes to this.
  • autocanceled: If hypertrack automatically cancels an action based on one of parameters defined by you when creating the action, its status changes to this.

Once completed or autocompleted or canceled or autocanceled, an action's status cannot be changed.

2.2.2. Timestamps
Property Type Description
created_at ISO datetime string Time at which the action was created
started_at ISO datetime string Time at which the action's status changed to started. If the action was created when there was no other pending action for that user, started_at would be same as created_at
completed_at ISO datetime string Time at which the action was completed. It could have been completed by you or autocompleted by hypertrack if you requested so when creating the action
canceled_at ISO datetime string Time at which the action was automatically expired by hypertrack, if it was expired
2.2.3. Places
Property Type Description
started_place JSON Place where the action's status changed to started
completed_place JSON Place where the action was completed
2.2.4. Distance and route
Property Type Description
distance Integer Distance traveled, in metres, between started_place and completed_place. For actions that haven't been completed yet, the distance is calculated till the current time
encoded_polyline String Route traveled by user, in Google's encoded polyline format. Use this to plot route on map
time_aware_polyline String Route traveled by user with timestamps, in hypertrack's time aware polyline format. Use this to replay the route

3. Expected movement properties

3.1. Defined by you when creating action

Property Type Description
expected_place JSON Place where the action is expected to be completed. It is used to calculate eta of an action, and once the action is completed it is used to check if action was completed at a place different from where it was expected to be
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

3.2. Derived by hypertrack

These properties are derived by hypertrack if expected_place was defined by you when creating the action. When deriving these properties:

  • the location of the user at created_at (the time that the action was created) is used as starting point and
  • expected_place is used as destination
3.2.1. Status
Property Type Description
arrival_status String Current sub status of the action. Possible values are leaving_now, on_the_way, arriving, arrived and moving_away. It is an empty string if expected_place is not defined by the user. It is an empty string if the action status is created. It starts getting updated once the action status changes to started and keeps getting updated till status changes to completed or autocompleted or canceled or autocanceled

Here is what each arrival_status value means:

  • leaving_now: As soon as action status changes to started, the arrival_status changes to leaving_now till the user leaves (moves 100 metres or more away from) the started_place.
  • on_the_way: Once the user moves leaves the started_place, arrival_status changes to this, till it changes to arriving
  • arriving: As soon as the user is close (within 400 metres) to the expected_place, arrival_status changes to this.
  • arrived: As soon as the user arrives (within 100 metres) at the expected_place, arrival_status changes to this.
  • moving_away: If the user is moving away from the expected_place and is not close to it, arrival_status changes to this.

Each of the above distance thresholds is haversine distance.

3.2.2. Timestamps
Property Type Description
eta ISO datetime string Current ETA. It is the time estimated to move from the current location of the user to the expected_place factoring for traffic
eta_at_creation ISO datetime string ETA estimated at the time when action was created. It is the time estimated to move from current location of the user at created_at time to the expected_place. It is useful in comparing how the the eta changes from the time that the action was created
3.2.3. Distance and route
Property Type Description
remaining_encoded_polyline String Shortest route, if the user drives from its current location to expected_place. It is the route that can be traveled in eta time
remaining_distance Integer Distance in metres, of encoded_polyline_to_arrival

Sample JSON

{
    <!-- Identifier properties -->
    # defined by you when creating action
    "unique_id": "order-1234-delivery",
    "collection_id": "order-1234",
    "type": "delivery",
    "user": {},
    "metadata": {},

    # set by hypertrack when action created
    "id": "8eb392bf-4b6f-4f3f-abf3-8143397da28e",
    "tracking_url": "https://trck.at/BTrc5w4",

    <!-- Actual movement properties -->
    # properties to program action - defined by you when creating action
    "is_autocomplete_at_expected_place": True,
    "is_autocomplete_at_creation": False,
    "schedule_autocancel_at": "2017-09-07T00:00:00.000000Z",

    # derived by hypertrack - status
    "status": "completed",
    "updated_at": "2017-09-06T07:36:15.516906Z",

    # derived by hypertrack - timestamps
    "created_at": "2017-09-06T07:16:28.380992Z",
    "started_at": "2017-09-06T07:16:28.380992Z",
    "completed_at": "2017-09-06T07:36:15.516906Z",
    "canceled_at": null,

    # derived by hypertrack - places
    "started_place": {},
    "completed_place": {},

    # derived by hypertrack - distance and route
    "distance": 10183, 
    "encoded_polyline": "",
    "time_aware_polyline": "",

    <!-- Expected movement properties -->
    # properties to program action - defined by you when creating action
    "expected_at": "2017-09-06T07:36:15.516906Z",
    "expected_place": {},

    # derived by hypertrack - status
    "arrival_status": "arrived",

    # derived by hypertrack - timestamps
    "eta_at_creation": "2017-09-06T07:36:15.516906Z",
    "eta": "2017-09-06T07:36:15.516906Z",

    # derived by hypertrack - distance and route
    "distance_to_arrival": 2134,
    "encoded_polyline_to_arrival": "",
}

Action collection

You can use Collections to club actions that are logicaly related to each other. E.g.,

  • A group of friends sharing their live location can represent multiple visit actions on our APIs
  • An order in your system can represent one pickup and one dropoff 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, session id, 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.

[warning] You don't need to create a collection to use multiple actions If there are multiple actions pending on a user, it is assumed that the user will complete them one by one in sequence. If there is no logical relationship between them, then you don't need to create multiple.

APIs to program actions

There are two APIs that you will necessarily need to program your use case using the Action entity.

API call Method URL Description
Create actions actions/ Creates one or more actions. Do use the parameters to program
Complete an action actions/<id>/complete/ Completes an existing action. You may skip this if you program hypertrack to autocomplete the action
Cancel an action actions/<id>/cancel/ Cancels an existing action. You may skip this if you program hypertrack to autocomplete the action

APIs to reprogram actions

Use these APIs to reprogram actions after creating them.

API call Method URL Description
Get sequence of actions users/<id>/sequence_actions/ Get the sequence in which actions are expected to be completed. Actions, by default, get sequenced in the order they are created
Update sequence of actions users/<id>/sequence_actions/ Update the sequence in which actions are expected to be completed
Update an action actions/<id>/ Edit an existing action object
Delete an action actions/<id>/ Delete an existing action object

APIs to consume actions

Once you create an action, hypertrack derives several useful properties on the Action entity. Retrieve these properties using the following APIs. These are building blocks that you can use to build your use case.

API call Method URL Description
Retrieve an action actions/<id>/ Retrieves an existing action object
Retrieve multiple actions actions/ Lists all actions objects. Use parameters to filter and order

APIs based on usecase

This is where you reap the rewards of programming actions. Use the API that is most relevant to what you are building.

API call Method URL Description Usecase
Meter an action actions/<id>/meter/ Returns actual movement properties for an action like distance traveled and route taken Useful if you are building mileage tracking
Track an action actions/<id>/track/ Returns all expected and actual movement properties of action objects, so that you can track the movement of a user in real-time Used by our live tracking visual and live location sharing visual
Retrieve placeline of an action actions/<id>/placeline/ Returns placeline for an action Used by our customer support visual
Retrieve events of an action actions/<id>/events/ Returns events for an action Used by our customer support visual
TODO Retrieve heatmap of actions actions/heatmap/ Returns heatmap of all the actions that can be visualised on a map Used by our operations monitoring visual

Aggregate APIs

These APIs return aggregates calculated on all actions filtered as per given parameters.

API call Method URL Description Usecase
TODO Aggregate actions by status actions/aggregate/status Returns count of actions by current status Used by our operations monitoring visual
TODO Aggregate actions by arrival_status actions/aggregate/arrival_status Returns count of actions by current arrival_status Used by our operations monitoring visual
TODO Aggregate actions by unexpected events actions/aggregate/events Returns count of actions by unexpected events. It is useful to infer how many actions were delayed or completed far away from the expected place Used by our operations monitoring visual

API reference

Create actions

Creates one or more new actions. The request body consists of a list of objects. One action is created for each object as per the parameters of the object.

If you create multiple actions for a user, the sequence of the objects in the list determines the sequence in which actions are expected to completed. Read more about sequence of actions here.

HTTP Request

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

Parameters

An action can be created using the following parameters.

Required parameter

An action is always created for a user who performs the action. The only required parameter to create an action is a unique identifier of an existing User object. One of the below two identifiers can be used.

Parameter Type Description
user_id UUID string id of existing user on hypertrack
user_unique_id String unique_id of existing user
Identifier parameters - optional
Parameter Type Description
unique_id String Unique identifier for the action object, based on your internal identifiers. Must not contain comma
collection_id String Identifier used to club and sequence actions, based on your internal identifiers. Must not contain comma
type String Identifier to differentiate between different types of actions performed by your users, like pickup, dropoff, delivery, visit, trip and so on. Defaults to task if no type is specified. Must not contain comma
metadata JSON Custom key-values pairs that may be useful context for your actions, specially in action visuals
Expected movement parameters - optional
Parameter Type Description
expected_place JSON Place where the action is expected to be completed. You can specify either the address or the location when creating a place. Only one of expected_place or expected_place_id must be specified
expected_place_id UUID string 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 ISO datetime string Time when the action is expected to be completed
Actual movement parameters - optional
Parameter Type Description
is_autocomplete_at_expected_place Boolean Flag that programs hypertrack to complete the action automatically, if the user arrives at the expected_place. This is useful if you don't want to depend on user input to complete the action. If it is set to true, then one of expected_place and expected_place_id MUST be specified. Defaults to false
is_autocomplete_at_creation Boolean Flag that programs hypertrack to create and complete the action at the same time. This is useful if you want to just annotate a point in time and location. If it is set to true, you don't need to complete the action later. Defaults to false
schedule_autocancel_at ISO datetime string Time at which you want hypertrack to automatically cancel the action, if it has not been completed till then. This is useful for garbage collection in case the action is not completed by the user. Default is 24 hours from created_at
Sample API Request
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "[{
       \"expected_place\": {\"address\": \"2200 Sand Hill Road Menlo Park CA USA\"},
       \"expected_at\": \"2016-03-09T07:00:00.00Z\"}]" \
     https://api.hypertrack.com/api/v2/actions/
Returns

Returns list of action objects, if all actions were successfully created. If the parameters of any object in the request body are invalid, then an error is returned and no action is created.

Complete an action

Complete the action with ID given in the request URL. You don't need to complete an action if you created it with any of the is_autocomplete properties set to true.

[warning] Recommend you to complete action using SDK method

If actions can be completed based on user interactions in the mobile app, we recommend doing that. You could use the SDK method to complete actions, as the SDK collects additional metadata at that time, leading to more accurate data collection.

HTTP Request

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

Parameters

No parameters

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v2/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. The action's properties that are derived by hypertrack at time of completion are calculated before returning the object.

Cancel an action

Cancel the action with ID given in the request URL. You don't need to cancel an action if you created it with the schedule_autocancel_at. If you expect user to not complete an action, it is recommended that you use one of the autocomplete or autocancel properties to get hypertrack to do it automatically.

[warning] Be sure before you cancel an action

When an action gets canceled, all its actual movement properties like distance, encoded_polyline and so on are derived to be null (for integer types) or empty string (for string types) or empty (for JSON types). You will

HTTP Request

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

Parameters

No parameters

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://api.hypertrack.com/api/v2/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. The action's properties that are derived by hypertrack at time of completion are set to null/empty before returning the object.

Update sequence of actions

Edit the sequence in which existing actions are expected to be completed. A GET request on the same URL will retrieve the current expected sequence of actions.

HTTP Request

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

Parameters

The request body must contain exactly one parameter.

Parameter Type Comment
action_ids Ordered list of UUID strings Action IDs ordered in the sequence in which the actions are expected to be completed. These actions must be of the specified user and not yet completed. If the list is not exhaustive, the incomplete actions of the user that have not been specified in the list are sequenced at the end of the specified list
Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"action_ids\": [\"d0ae4912-2074-45ef-a7c0-76be58639ea9\", \"d0ae4912-2074-45ef-a7c0-76be58639ea9\"]}" \
     https://api.hypertrack.com/api/v2/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/sequence_actions/
Returns

Returns a ordered list of action IDs that represents the updated action sequence, if the update was successful.

Update an action

Edit an existing action object. You can use this API to change the properties that you set when creating the action like unique_id, expected_place and so on.

HTTP Request

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

Parameters

Pass only those parameters that are corresponding to the properties that you want to update. You can use any of the

Note that you cannot update the user property of an action.

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"type\": \"pickup\", \"unique_id\": \"CRN1234\"}" \
     https://api.hypertrack.com/api/v2/users/d0ae4912-2074-45ef-a7c0-76be58639ea9/
action = hypertrack.Action.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
action.type = 'pickup'
action.unique_id = 'CRN1234'
action.save()
hypertrack.action
    .update(
        "d0ae4912-2074-45ef-a7c0-76be58639ea9",
        {
            "type": "pickup",
            "unique_id": "CRN1234"
        }
    );
Returns

Returns the updated action object, if the update was successful.

Retrieve an action

Retrieves an action object with the id.

HTTP Request

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

Sample API Request
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/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.

Retrieve multiple actions

Lists all actions objects.

HTTP Request

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

Parameters

You can use any of the optional filtering or ordering parameters.

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X GET \
     https://api.hypertrack.com/api/v2/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.

Delete Action

Delete an existing action object.

HTTP Request

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

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X DELETE \
     https://api.hypertrack.com/api/v2/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.

Meter an action

For an action, this API returns

  • actual movement properties like duration, distance traveled, route taken and so on, between the time that the action started and it was completed
  • optimal movement properties like shortest distance between the place where the action started and where it completed

Note that an action that has not yet started or has been canceled returns null values in Meter API.

HTTP Request

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

Sample API Request
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/actions/ce2102c3-b411-4481-b13e-87559f2b441f/meter/
Returns

Returns

  • action object and
  • additional actual and optimal movement properties, which are detailed below.

At the time of the API call if action status is

  • created (i.e. not started yet) then all the properties will have null value
  • started then all actual movement properties are computed between started_at and updated_at (timestamp when hypertrack last heard from the device), and optimal movement properties are null
  • completed or autocompleted then all the below properties are computed between started_at and completed_at
  • canceled or autocanceled then all the properties will have null value
Actual movement properties

These properties are calculated between started_at and completed_at.

Property Type Description
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 that the user was moving with that activity type. TODO- add link
distance_by_activity JSON Distance traveled, in metres, split by activity type. In the JSON, each key is an activity type and the value is the distance traveled by user while moving with that activity type. Possible keys are total, drive, cycle, run or walk
confidence String Confidence in distance traveled computation. Possible values are high and low
confidence_reason String Reason for low confidence in actual movement properties. If confidence is high, this is empty string

Properties of duration_by_activity JSON

Property Type Description
total Integer Time difference, in seconds between started_at and completed_at
drive Integer Duration, in seconds for which user was driving
cycle Integer Duration, in seconds for which user was cycling
walk Integer Duration, in seconds for which user was walking
stop Integer Duration, in seconds for which user was stopped
unknown_location_disabled Integer 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
unknown_sdk_killed Integer Duration, in seconds for which the hypertrack SDK was killed on user's device
unknown_device_off Integer Duration, in seconds for which user's device was switched off. This is will always be 0 for iOS devices because hypertrack is unable to infer if device was switched off on them
unknown_tracking_stopped Integer Duration, in seconds for which the user's device was not being tracked as stopTracking() had been called
Optimal movement properties
Property Type Description
shortest_encoded_polyline String Shortest route, if the user drives from started_place to completed_place
shortest_distance Integer Distance of shortest_encoded_polyline
Sample response JSON
{
    "id": "00003703-e65f-49bf-a76f-f73727afbb86",
    <!-- all action properties -->

    <!-- actual movement properties -->
    "duration_by_activity": {
        "total": 1746,
        "drive": 1600,
        "cycle": 0,
        "run": 0,
        "walk": 0,
        "stop": 46,
        "unknown_location_disabled": 100,
        "unknown_sdk_killed": 0,
        "walk": 0,
        "unknown_device_off": 0,
        "unknown_tracking_stopped": 0,
    }
    "distance_by_activity": {
        "total": 120
        "drive": 100,
        "cycle": 0,
        "run": 0,
        "walk": 20,
    }
    "confidence": "high",
    "confidence_reason": "distance may be inaccurate as user location was disabled for long",

    <!-- optimal movement properties -->
    "shortest_distance": 80,
    "shortest_encoded_polyline": "",
}

Track an action

For an action, this API returns

  • expected movement properties like ETA, expected route, derived using expected_place and expected_at.
  • actual movement properties like duration, distance traveled, route taken and so on, between the time that the action started and current time

[warning] Recommend you to define expected_place to make the most of track API

If you don't define expected_place while creating an action hypertrack won't be able to derive these useful expected movement properties

HTTP Request

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

Sample API Request
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/actions/ce2102c3-b411-4481-b13e-87559f2b441f/track/
Returns

Returns

  • action object and
  • a display object (JSON) with the following properties. These properties are derived using the properties of action object. If you are creating a visual for tracking experience you can use these properties directly rather than deriving them from the action properties.
Property Type Description
distance_unit String The unit in which the distance values should be displayed. Possible values are mi (if the user is moving in USA) and km (elsewhere in the world)
status_text String The status that should be shown on a tracking experience. Its a well formatted string derived using the status property of action, arrival_status of action, is_tracking property of user, current activity type of user, location_status of user and network_status of user
is_delayed Boolean This is set to true if the eta if greater than the expected_at. In all other cases including when no expected_at is defined for the action, it is false
duration_elapsed Integer Time difference in seconds, between started_at and updated_at
account_logo URL string URL of the logo of your account. If specified, the logo is displayed on the live tracking experience. You can upload your logo in dashboard settings- TODO
Status text

status_text is derived by hypertrack to give you a status that you can use out of the box in your tracking experience visual rather than using the status properties of action and user to derive it yourself. Here are its possible values:

Value Description
Completing another <action_type> Action status is created. Its not started yet because another action of type is started currently
Leaving now Action arrival_status is leaving_now and action status is started
Driving Action arrival_status is on_the_way or moving_away, action status is started and user current activity type is drive
Cycling Action arrival_status is on_the_way or moving_away, action status is started and user current activity type is cycle
Running Action arrival_status is on_the_way or moving_away, action status is started and user current activity type is run
Walking Action arrival_status is on_the_way or moving_away, action status is started and user current activity type is walk
Stopped Action arrival_status is on_the_way or moving_away, action status is started and user current activity type is stop
Tracking unavailable Action status is started and location is unavailable (User current location_status is disabled or denied OR user is_tracking is false OR user network_status is disconnected)
Arriving Action arrival_status is arriving and action status is started
Arrived Action arrival_status is arrived and action status is started
Completed Action status is completed or autocompleted, no matter what the arrival_status or any other user property is
Canceled Action status is canceled or autocanceled, no matter what the arrival_status is or any other user property is
Sample response JSON
{
    "id": "00003703-e65f-49bf-a76f-f73727afbb86",
    <!-- all action properties -->

    <!-- display -->
    "display": {
        "distance_unit": "km",
        "status_text": "Arriving",
        "is_delayed": false,
        "duration_elapsed": 200,
        "account_logo": ,
    }
}

Retrieve placeline of an action

HTTP Request

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

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/actions/00003703-e65f-49bf-a76f-f73727afbb86/placeline/
Returns

Returns

Sample API Response
{
    "id": "00003703-e65f-49bf-a76f-f73727afbb86",
    <!-- all action 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",
      "confidence": "high",

      # derived from location
      "distance": 310.473,
      "encoded_polyline": "aiseFr_ajVAA??fA{A??LO??l@t@??r@bA??PT??HL??r@`A??`CcD",
      "time_aware_polyline": "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",
      "confidence": "medium",
      "step_count": 301,
      "step_distance": 210,

      # 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": []
    },
    {
      "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",
      "confidence": null,
      "unknown_reason": "activity_permission_denied"

      "distance": 310.47333797811655,
      "encoded_polyline": "LO??l@t@??r@bA??PT??HL??r@`A??`CcD",
      "time_aware_polyline": "{ykx@bA????PT????HL????r@`A????`CcDA",
      "health": [],
    },
    ]
}

Retrieve events of an action

HTTP Request

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

Sample API Request
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v2/actions/00003703-e65f-49bf-a76f-f73727afbb86/events/
Returns

List of events that have been generated in the lifecycle of this action. Each event has the following properties:

Property Type Description
type String Type of event. Here is the list of all possible event types
recorded_at ISO datetime string Time when this event was recorded
location JSON Location of user when this event was recorded
value Integer A useful value, if any associated with the event. Typically it is a unit of distance (metres) or time (seconds). For example, for action.delayed event value captures the delay in seconds, for action.completed_at_different_place_than_expected event value captures the distance between completed_place and expected_place in metres, and for action.arriving event value is null
Sample API Response
[{
    "type": "action.arriving",
    "recorded_at": "2017-09-06T07:32:00.000000Z",
    "location": {
        "geojson": {
          "type": "Point",
          "coordinates": [
            72.8938115,
            19.1131683
          ]
        },
    },
    "value": null,
},{
    "type": "action.delayed",
    "recorded_at": "2017-09-06T07:36:28.380992Z",
    "location": null,
    "value": 500,   # in seconds
},{
    "type": "action.completed_late",
    "recorded_at": "2017-09-06T07:36:28.380992Z",
    "location": null,
    "value": 58321, # in seconds
},{
    "type": "action.completed_at_different_place_than_expected",
    "recorded_at": "2017-09-06T07:36:28.380992Z",
    "location": {
        "geojson": {
          "type": "Point",
          "coordinates": [
            72.8938115,
            19.1131683
          ]
        },
    },
    "value": 500,   # in metres
}]

Filtering parameters

You can pass the following parameters as arguments in the URL of any GET API that returns a list. The list can be filtered using one or more parameters. All of them are optional. You will find them particularly useful in APIs to retrieve multiple actions, and retreive analytics data.

Identifier filters

Parameter Type Description
id UUID String Filter action that has this id. To filter multiple actions, use a comma separated list of ids
unique_id String Filter action that has this unique_id. To filter multiple actions, use a comma separated list of unique ids
collection_id String Filter actions that have this collection_id
user_id String Filter actions of specified user. To filter for multiple users, use a comma separated list of user ids
user__unique_id String Filter actions of specified user. To filter for multiple users, use a comma separated list of user ids
user__group_id String Filter actions of users in the specified group_id
type String Filter actions of this type. To filter for multiple types, use a comma separated list of types

Datetime filters

Parameter Type Description
min_created_at ISO datetime string Filter actions which were created after this datetime
max_created_at ISO datetime string Filter actions which were created before this datetime
min_started_at ISO datetime string Filter actions which started after this datetime
max_started_at ISO datetime string Filter actions which started before this datetime
min_completed_at ISO datetime string Filter actions which were completed after this datetime
max_completed_at ISO datetime string Filter actions which were completed before this datetime
min_expected_at ISO datetime string Filter actions which were expected after this datetime
max_expected_at ISO datetime string Filter actions which were expected before this datetime

Status filters

Parameter Type Description
status String Filter actions that have this status. To specify multiple statuses, use a comma separated list
arrival_status String Filter actions that have this arrival_status. To specify multiple statuses, use a comma separated list

Location filters

Parameter Type Description
completed_location__bbox comma separated 4-tuple of lat and long Filter actions that were completed within a bounding box. Specified as max_lng,max_lat,min_lng,min_lat

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, started_at, completed_at, expected_at or eta. If you order in descending order, actions that have null timestamp will be ordered last.

Sample to get list of actions ordered by the most recently completed first

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

Identifier ordering values

unique_id, collection_id, type or user_id, ordered lexicographically.

Status ordering values

status or arrival_status, ordered lexicographically.

Movement properties' ordering values

distance_to_arrival, distance or duration

Action guides [TODO]

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 & route traveled 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 route 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 route 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 ""