Action

An Action is a pickup, delivery, visit or any other transaction event being performed by the User.

Action object's properties

Property Type Description
id uuid string Unique identifier for the object
user JSON The user object to which the action was assigned
type string The type of action, can be pickup, delivery, dropoff, visit, stopover or task
lookup_id string An identifier for the action that can based on your internal id
collection_id string An identifier to club actions
assigned_at ISO datetime string The time at which the action was assigned to the user
scheduled_at ISO datetime string The scheduled time by when the action should be completed
expected_place JSON The place object where the action is to be completed
status string The action status. Can be created, assigned, started, completed, canceled, suspended (automatically by HyperTrack if it is not completed or canceled for a long time)
sub_status string Granular action status. Can be not_started, in_queue (for assigned status) leaving_now, on_the_way, arriving, arrived (for started status)
initial_eta ISO datetime string The initial eta calculated for the action
eta ISO datetime string The current eta for the action, calculated in real-time
completed_place JSON The place where the action was completed
completed_at ISO datetime string The time at which the action was completed
suspended_at ISO datetime string The time at which the action was suspended, if it was suspended instead of being completed
canceled_at ISO datetime string The time at which the action was canceled, if it was canceled
tracking_url string The URL at which this action can be tracked. This URL can be shared with anyone
created_at ISO datetime string Timestamp of when action was created
modified_at ISO datetime string Timestamp of when action was modified
display JSON Imp details for user for an action that has been assigned or started like duration_remaining and distance_remaining
event_flags JSON array List of unexpected events that have been generated for this action. Each event has fields type and value. Here is the list of all event types. Example of this property: [{ type: "action.completed_late", value: 58321 }, { type: "action.completed_at_different_place_than_expected", value: 1256 }]. Time value is in seconds and distance in meters
metadata JSON Metadata about the action that may be useful for you to see when an action is tracked
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

Action collections

In some use-cases, actions would need to be logically clubbed together. For example,

  • 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
  • A meetup in your system can represent multiple visit 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, milk run id, or meetup id, for above examples). You can use collection_id as a param in the APIs that create, update or retrieve actions.

The collection_id is different from the lookup_id in following ways.

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

API calls

Create an Action

Creates a new action object.

HTTP Request

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

Returns

Returns an action object if the call succeeded.

Parameters

Parameter Required Description
expected_place No The Place object where the action will be performed. Only one of expected_place or expected_place_id must be specified.
expected_place_id No The id of the Place where the action will be performed. This parameter can be used 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
scheduled_at No The scheduled time by when the action should be completed
type No The type of the action, possible values are pickup, delivery, dropoff, visit, stopover or task. Defaults to task.
lookup_id No An id that you can specify based on your internal ids
collection_id No An identifier to club actions, for example, one pickup and delivery. Read more about collections here
user_id No This assigns the action to a User. It has the same effect as Assign Action to a User API below
metadata No Metadata about the action that may be useful for you to see when an action is tracked
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')

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_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']})

Complete an Action

Completes an Action.

[warning] Completing actions

If marking actions is done using interactions in the mobile app, it is recommended to use the SDK methods for completing actions. This way the action has the right metadata for more accurate data collection.

HTTP Request

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

Returns

Returns an action object if the call succeeded.

Parameters

Parameter Required Description
completed_at No Timestamp when action is completed, default to current time
completion_location No Location at which action is completed
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()

Cancel Action

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

HTTP Request

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

Returns

Returns an action 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/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()

Retrieve an Action

Retrieves an action object with the id.

HTTP Request

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

Returns

Returns an action object if the call succeeded.

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')

Update an action

Edit an existing action object.

HTTP Request

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

Returns

Returns the updated action object.

Parameters

Parameter Required Description
type string The type of action, can be pickup, delivery, dropoff, visit, stopover, trip or task
lookup_id string An identifier for the action that can based on your internal ids
collection_id string An identifier for the collection of actions that can based on your internal ids. Read more about collections here
scheduled_at ISO datetime string The scheduled time by when the action should be completed
expected_place JSON The place object where the action is to be completed
metadata JSON Metadata about the action that may be useful for you to see when an action is tracked
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"
        }
    );

Meter an Action

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

HTTP Request

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

Returns

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

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()

Retrieve multiple Actions

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

HTTP Request

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

Returns

Returns a list of actions.

Parameters

Parameter Required Description
page_size No Maximum number of objects to return, default is 50
user_id No Filter actions that are assigned to a user
lookup_id No Filter actions by lookup id
collection_id No Filter actions by collection id. Read more about collections here
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/?collection_id=COLLECTION_ID&page_size=20
actions = hypertrack.Action.list()
hypertrack.action
    .list()
    .then(function(actions) {});
HyperTrack::Action.list

Delete an Action

Delete an existing action object.

HTTP Request

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

Returns

Empty response if the object is deleted.

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);

Retrieve analytics data

You can 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. You can get this data for one or more actions by using the filter parameters specified below.

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

HTTP Request

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

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

This is how a sample response looks like.

{
    "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
        },
        ...
    ]
}

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, retrieve placeline data and retreive analytics data.

Datetime filters

Parameter Type Description
min_created_at ISO datetime Filter actions which were created after this datetime
max_created_at ISO datetime Filter actions which were created before this datetime
min_assigned_at ISO datetime Filter actions which were assigned after this datetime
max_assigned_at ISO datetime Filter actions which were assigned before this datetime
min_completed_at ISO datetime Filter actions which were completed after this datetime
max_completed_at ISO datetime Filter actions which were completed before this datetime
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

Identifier filters

Parameter Type Description
id UUID String Filter action that has this id. To get multiple actions, use a comma separated list of ids
lookup_id string Filter action that has this lookup_id. To get multiple actions, use a comma separated list of lookup ids
collection_id string Filter actions that have this collection_id. Only one collection id can be passed
type string Filter actions that have this type. To specify multiple types, use a comma separated list
user_id UUID string Filter actions that were assigned to user with this user_id. To specify multiple ids, use a comma separated list
curl "https://api.hypertrack.com/api/v1/actions/placeline/?id=41caa9f2-ad63-4a8b-98ed-1414c372e1ce,4e2a8344-9864-4473-864f-e223dec208b3"
  -H "Authorization: token YOUR_SECRET_KEY"

State filters

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

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

Value Description
created_at Order actions by assigned_at
scheduled_at Order actions by scheduled_at. If you order in descending order, actions that have null scheduled_at will be ordered last
completed_at Order actions by completed_at. If you order in descending order, actions that have null completed_at will be ordered last
canceled_at Order actions by canceled_at. If you order in descending order, actions that have null canceled_at will be ordered last

Sample to get actions in ascending order of assigned_at

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

Identifier ordering values

Value Description
lookup_id Order by lookup_id, lexicographically
collection_id Order by collection_id, lexicographically
type Order by type. Useful if you want to group actions by type
user_id Order by id of assigned user. Useful if you want to group actions assigned to same user

State ordering values

Value Description
status Order by status. Useful if you want to group actions by status
eta_in_seconds Order by eta. If you order in descending order, actions that have null eta (actions that have completed status or canceled status or don't have an expected_place) will be ordered last
remaining_distance Order by distance remaining for action as per expected_place

Sample to get actions that are ongoing (assigned status) in descending order of eta

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://api.hypertrack.com/api/v1/actions/?status=assigned&ordering=-eta_in_seconds
</div></div>

results matching ""

    No results matching ""