Trip

The Trip object represents a journey taken by the Driver.

When a Trip is live, the mobile SDK sends locations for the Driver, forming a location stream for the Trip. These locations are appended to the encoded polylines of the Trip, and can be retrieved in multiple ways. At a point, a Driver can only be on one Trip.

The Trip object

Property Type Description
id uuid string Unique identifier for the object
status string Status of the object. Can be one of initiated, live, suspended and ended.
driver JSON The driver object who is on the trip
started_at ISO datetime string The time at which the trip started
start_location GeoJSON point The location where the trip started
ended_at ISO datetime string The time at which the trip ended
end_location GeoJSON point The location where the trip ended
tasks array An array of ids of tasks that are on the trip
vehicle_type string The vehicle type to be used for the trip
distance integer The distance traveled on the trip, in meters
encoded_polyline string The encoded polyline of locations of the trip
time_aware_polyline string The time aware polyline of the locations and timestamps
is_auto_ended boolean Boolean to indicate if the trip should end after the last task is completed
has_ordered_tasks boolean Boolean to indicate if the tasks on the trip have a pre-defined sequence
created_at ISO datetime string Timestamp of when trip was created
modified_at ISO datetime string Timestamp of when trip was modified

Trip statuses

Status Definition
initiated When a trip is created, but no locations have been received for the trip so far. When a trip is initiated, the SDK is sent a message to start transmitting locations.
live When a trip receives the first location, it goes from initiated to live.
suspended When connection with the driver has been lost for >60 mins, the trip goes into suspended state. Whenever the driver comes back online, the trip is resumed as live.
ended When a trip ends, status moves from live to ended.

Create a Trip

Creates a new trip object. By default, it also starts the trip.

HTTP Request

POST https://app.hypertrack.io/api/v1/trips/

Returns

Returns a trip object if the call succeeded.

[warning] Starting trips in SDK

For the trip to be started in the SDK using the server-side API, the SDK must be connected with the same driver id. Read the trips guide for Android and iOS.

Parameters

Parameter Required Description
driver_id No The id of the driver who will be on trip. If not specified, a new driver will be created for the purpose of the trip
start_location No The start location of the trip
tasks No The array of task ids to be performed on the trip
vehicle_type No The vehicle type to be used in the trip. If not specified, this defaults to vehicle type of driver. Possible types are walking, bicycle, motorcycle, car, 3-wheeler, van
has_ordered_tasks No Set true to indicate the tasks have a pre-defined sequence as specified in tasks. Default is false.
is_auto_ended No Set false if the trip should not end after the last task is completed. Default is true, and the trip ends after the last task is completed.
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"driver_id\": \"3f7c936b-b69d-4f7d-8119-ce08dde4c377\", \"tasks\": [\"b2249ba8-e88c-455e-b02f-672677828ddc\"]}" \
     https://app.hypertrack.io/api/v1/trips/
hypertrack.Trip.create(
    driver_id='3f7c936b-b69d-4f7d-8119-ce08dde4c377',
    tasks=['b2249ba8-e88c-455e-b02f-672677828ddc']
)

Example response

{
  "created_at": "2016-12-25T14:51:10.518251Z",
  "driver_id": "3f7c936b-b69d-4f7d-8119-ce08dde4c377",
  "end_location": null,
  "ended_at": null,
  "eta": null,
  "has_ordered_tasks": false,
  "id": "ce2102c3-b411-4481-b13e-87559f2b441f",
  "initial_eta": null,
  "is_auto_ended": true,
  "modified_at": "2016-12-25T14:51:10.576804Z",
  "start_location": null,
  "started_at": "2016-12-25T14:51:10.516544Z",
  "status": "live",
  "tasks": ["b2249ba8-e88c-455e-b02f-672677828ddc"],
  "vehicle_type": "car"
}

End a Trip

Ends a live trip by trip id.

[warning] Incomplete tasks

If there are incomplete tasks on the trip when it is ended, the tasks are marked as aborted.

HTTP Request

POST https://app.hypertrack.io/api/v1/trips/<id>/end/

Returns

Returns the trip object if the call succeeded.

Parameters

Parameter Required Description
end_location No Location where the trip ends
end_time No Time at which the trip ends, defaults to current time
curl -H "Authorization: token YOUR_PK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://app.hypertrack.io/api/v1/trips/ce2102c3-b411-4481-b13e-87559f2b441f/end/

% sample lang="python" %}

trip = hypertrack.Trip.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
trip.end()

Example response

{
  "created_at": "2016-12-25T14:51:10.518251Z",
  "driver_id": "3f7c936b-b69d-4f7d-8119-ce08dde4c377",
  "end_location": null,
  "ended_at": null,
  "eta": null,
  "has_ordered_tasks": false,
  "id": "ce2102c3-b411-4481-b13e-87559f2b441f",
  "initial_eta": null,
  "is_auto_ended": true,
  "modified_at": "2016-12-25T14:51:10.576804Z",
  "start_location": null,
  "started_at": "2016-12-25T14:51:10.516544Z",
  "status": "ended",
  "tasks": ["b2249ba8-e88c-455e-b02f-672677828ddc"],
  "vehicle_type": "car"
}

Retrieve a Trip

Retrieves a trip object with the id.

HTTP Request

GET https://app.hypertrack.io/api/v1/trips/<id>/

Returns

Returns a trip object if a valid identifier was provided.

curl -H "Authorization: token YOUR_PK_TOKEN" \
     -X GET \
     https://app.hypertrack.io/api/v1/trips/f3ead2ae-dc0a-4a7e-85be-74ee51d9d70a/
trip = hypertrack.Trip.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')

Delete a Trip

Delete an existing trip object.

HTTP Request

DELETE https://app.hypertrack.io/api/v1/trips/<id>/

Returns

Empty response if the object is deleted.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X DELETE \
     https://app.hypertrack.io/api/v1/trips/f3ead2ae-dc0a-4a7e-85be-74ee51d9d70a/
trip = hypertrack.Trip.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
trip.delete()

Example response

{}

List all Trips

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

HTTP Request

GET https://app.hypertrack.io/api/v1/trips/

Returns

Returns a list of trips.

Parameters

Parameter Required Description
page_size No Maximum number of objects to return, default is 50
driver_id No Filter trips for a particular driver id
id No Filter trips with a comma separated list of ids
status No Filter trips for a particular status, can be one of initiated, live, ended, suspended
min_date No Filter objects by minimum created at date
max_date No Filter objects by maximum created at date
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -X GET \
     https://app.hypertrack.io/api/v1/trips/?status=live
trips = hypertrack.Trip.list()

Add Task to a Trip

This API lets you add Tasks to a live Trip. Only tasks that have not been completed can be added to a Trip.

Parameter Required Description
task_id Yes The id of the task to be added
curl -H "Authorization: token test_token" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"task_id\":\"3a36b6df-a7e7-40d0-86b7-b5aae1ce3a2b\"}" \
     https://app.hypertrack.io/api/v1/trips/41caa9f2-ad63-4a8b-98ed-1414c372e1ce/add_task/
trip = hypertrack.Trip.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
trip.add_task(task_id='3a36b6df-a7e7-40d0-86b7-b5aae1ce3a2b')

Remove Task from a Trip

This API lets you remove Tasks to a live Trip. Only tasks that are on the Trip and have not been completed can be removed.

Parameter Required Description
task_id Yes The id of the task to be removed
curl -H "Authorization: token test_token" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"task_id\":\"3a36b6df-a7e7-40d0-86b7-b5aae1ce3a2b\"}" \
     https://app.hypertrack.io/api/v1/trips/41caa9f2-ad63-4a8b-98ed-1414c372e1ce/remove_task/
trip = hypertrack.Trip.retrieve('ce2102c3-b411-4481-b13e-87559f2b441f')
trip.remove_task(task_id='3a36b6df-a7e7-40d0-86b7-b5aae1ce3a2b')

Change sequence of Tasks of a Trip

This API lets you reorder Tasks of a live Trip. This can only be done for Trips that have has_ordered_tasks as true.

Parameter Required Description
task_order Yes Array of task ids in the new sequence. Must have all ids of tasks on the trip.
curl -H "Authorization: token test_token" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"task_order\":[\"3a36b6df-a7e7-40d0-86b7-b5aae1ce3a2b\", \"77b9a3fa-a3ab-4840-aadb-cd33442ca45b\"]}" \
     https://app.hypertrack.io/api/v1/trips/41caa9f2-ad63-4a8b-98ed-1414c372e1ce/change_task_order/

results matching ""

    No results matching ""