Driver

The Driver object represents the user who is being tracked. Driver object has a one-to-one mapping with the device, and cannot be used across devices.

The Driver object

Property Type Description
id uuid string Unique identifier for the object
name string Name of the driver
vehicle_type string Vehicle of the driver
phone string E164 formatted phone number of driver
fleet_id string The id of the fleet to which this driver belongs
lookup_id string A unique id that you can add to the driver to identify
is_online boolean True if the driver is currently actively transmitting, false otherwise
is_ontime boolean True if the driver is ontime for the live tasks, false if delayed, and null if not active or ETA is unknown
last_heartbeat ISO datetime string Date time for last communication with the driver's device
last_known_location JSON The last known location of the driver with the speed, bearing, location accuracy and recorded time fields
status JSON The device status of the driver with device model, maufacturer, battery, SDK version
battery_level float The battery level of the driver at last_heartbeat timestamp
location deprecated GeoJSON The last know location of a driver; use last_known_location.location instead
location_recorded_at deprecated ISO datetime string The time at which the last known location of the driver was recorded; use last_known_location.recorded_at instead
created_at ISO datetime string Timestamp of when driver was created
modified_at ISO datetime string Timestamp of when driver was last modified

Create a Driver

This API will create and return a Driver object.

HTTP Request

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

Returns

Returns a driver object if the call succeeded.

Parameters

Parameter Required Description
vehicle_type Yes The default vehicle type of the driver. Must be one of "walking, bicycle, motorcycle, car, 3-wheeler, van, flight, train, ship".
name No Name of the driver
phone No E164 formatted phone number of the driver
photo No A photo file of the driver
lookup_id No A unique id that you can add to the driver to search
fleet_id No The identifier of the fleet to which the driver belongs
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"name\": \"Driver name\", \"vehicle_type\": \"car\", \"phone\": \"+16502469293\"}" \
     https://app.hypertrack.io/api/v1/drivers/
hypertrack.Driver.create(
    name='Driver name',
    vehicle_type='car',
    phone='+16502469293'
)
hypertrack.driver.create(
    { name: 'Driver name', vehicle_type: 'car', phone: '+16502469293'},
    function(err, driver) {
        err; // null if no error occurred
        driver; // the created driver object
    }
);
HyperTrackClient client = new HyperTrackClient("YOUR_SK_TOKEN");
DriverFactory driverFactory = new DriverFactory(client);
Map<String, Object> driverParams = new HashMap<>();
driverParams.put("name", "Driver name");
driverParams.put("vehicle_type", "car");
driverParams.put("phone", "+16502469293");
Driver driver = driverFactory.create(driverParams);
{
   "id" : "941e13ea-7d59-4ebd-b305-33117a72e3c9",
   "phone" : "+16502469293",
   "name" : "Driver name",
   "last_heartbeat" : null,
   "location" : null,
   "photo" : null,
   "vehicle_type" : "car",
   "fleet_id" : null,
   "lookup_id" : "",
   "is_online" : false,
   "is_ontime" : null,
   "status" : {
      "location_enabled" : true,
      "last_updated_at" : null,
      "device_id" : "",
      "is_connected" : true,
      "battery_percentage" : null,
      "location_permission" : true,
      "device_manufacturer" : "",
      "device_model" : "",
      "driver_id" : "941e13ea-7d59-4ebd-b305-33117a72e3c9",
      "battery_charging_status" : "",
      "sdk_version" : "",
      "has_old_sdk" : true
   },
   "last_known_location" : {},
   "battery_level" : null,
   "location_recorded_at" : null,
   "created_at" : "2016-12-22T03:27:44.949189Z",
   "modified_at" : "2016-12-22T03:27:44.949216Z"
}

Retrieve a Driver

Retrieves a driver object with the id.

HTTP Request

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

Returns

Returns a driver object if a valid identifier was provided.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://app.hypertrack.io/api/v1/drivers/d0ae4912-2074-45ef-a7c0-76be58639ea9/
driver = hypertrack.Driver.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
HyperTrackClient client = new HyperTrackClient("SECRET_KEY");
DriverFactory driverFactory = new DriverFactory(client);
Driver driver = driverFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");
System.out.println(driver.getProperties());
hypertrack.drivers.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9', function(err, driver) {
  err; // null if no error occurred
  driver; // the retrieved driver object
})

Update a Driver

Edit an existing driver object.

HTTP Request

PATCH https://app.hypertrack.io/api/v1/drivers/<id>/

Returns

Returns the updated driver object.

Parameters

Parameter Required Description
vehicle_type No The default vehicle type of the driver. Must be one of "walking, bicycle, motorcycle, car, 3-wheeler, van, flight, train, ship".
name No Name of the driver
phone No E164 formatted phone number of the driver
photo No URL of the photo to be assigned to the driver
lookup_id No A unique id that you can add to the driver to search
fleet_id No The identifier of the fleet to which the driver belongs
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d "{\"name\": \"Driver name\", \"vehicle_type\": \"car\", \"phone\": \"+16502469293\"}" \
     https://app.hypertrack.io/api/v1/drivers/d0ae4912-2074-45ef-a7c0-76be58639ea9/
driver = hypertrack.Driver.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
driver.name = 'New name'
driver.photo = 'https://photo-url.com/photo.png'
driver.save()
HyperTrackClient client = new HyperTrackClient("SECRET_KEY");
DriverFactory driverFactory = new DriverFactory(client);
Driver driver = driverFactory.retrieve("d0ae4912-2074-45ef-a7c0-76be58639ea9");
Map<String, Object> newParams = new HashMap<>();
driverParams.put("name", "New name");
driverParams.put("photo", "https://photo-url.com/photo.png");

driverFactory.patch(driver, newParams);
System.out.println(driver.getProperties());
newParams = {name: 'New name', photo: 'https://photo-url.com/photo.png'}
hypertrack.drivers.update('d0ae4912-2074-45ef-a7c0-76be58639ea9', newParams, function(err, driver) {
  err; // null if no error occurred
  driver; // the retrieved driver object
})

Delete a Driver

Delete an existing customer object.

HTTP Request

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

Returns

Empty response if the object is deleted.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X DELETE \
     https://app.hypertrack.io/api/v1/drivers/d0ae4912-2074-45ef-a7c0-76be58639ea9/
driver = hypertrack.Driver.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
driver.delete()

Example response

{}

List all Drivers

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

HTTP Request

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

Returns

Returns a list of drivers.

Parameters

Parameter Required Description
page_size No Maximum number of objects to return, default is 50
name No Filter drivers with names that contain this string
id No Filter drivers with a comma separated list of ids
fleet_id No Filter driver objects by fleet
bbox No Filter driver objects by bounding box, specified as max_lng,max_lat,min_lng,min_lat
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" \
     -H "Content-Type: application/json" \
     -X GET \
     https://app.hypertrack.io/api/v1/drivers/
drivers = hypertrack.Driver.list()

Get Driver overview

Retrieves the overview of an existing driver's performance. Supply the unique identifier that was returned on driver creation.

HTTP Request

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

Returns

Returns performance metrics for the driver object.

Parameters

Parameter Required Description
min_date No Minimum date as ISO datetime string to get statistics for a driver
max_date No Maximum date as ISO datetime string to get statistics for a driver
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://app.hypertrack.io/api/v1/drivers/d0ae4912-2074-45ef-a7c0-76be58639ea9/overview/

Example response

{
  "total_tasks":2, // total tasks performed in given date range
  "tasks_trend":[
    1,
    1
  ], // Number of tasks per day, oldest first
  "data_usage":47281, // data usage in bytes
  "utilization":588, // total seconds tracked
  "on_time_performance":1.0, // ratio of on time to total tasks. Multiply this by 100 to get percentage
  "utilization_per_day": 294, // total seconds track per active day
  "active_days": 2 // number of days driver was active in given time rande
}

Get map list for all Drivers

Returns a minimal list of your drivers with location to display on a map

HTTP Request

GET https://app.hypertrack.io/api/v1/drivers/map_list/

Returns

Returns a list of drivers with their locations.

Parameters

Parameter Required Description
min_date No Minimum created date as ISO datetime string to filter drivers
max_date No Maximum created date as ISO datetime string to filter drivers
fleet_id No Filter only drivers of a particular fleet
page_size No The number of entries to return in a page (maximum of 200)
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X GET \
     https://app.hypertrack.io/api/v1/drivers/map_list/

Assign Tasks to a Driver

This API will assign a list of Tasks to a Driver. We recommend using this after you have created tasks and want to start tracking them. If driver is on a Trip when the call is made, we add these tasks to the currently running Trip, else we create a new Trip and start tracking it for you. When all tasks are marked completed, we end the Trip and stop tracking.

HTTP Request

POST https://app.hypertrack.io/api/v1/drivers/<id>/assign_tasks/

Returns

Returns a Trip object to which the tasks are added.

Parameters

Parameter Required Description
task_ids Yes List of task ids to be assigned to the driver
start_location No A start location for the Driver's new Trip, sent as a geojson object. This only reflects if the Driver is not already on a Trip.
curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d "{\"task_ids\": [\"6daacb03-6f02-4c60-b084-e9ffcd9eaf56\", \"37ae09b4-4801-48cb-bc50-99a7ee53f257\"]}" \
     https://app.hypertrack.io/api/v1/drivers/d0ae4912-2074-45ef-a7c0-76be58639ea9/assign_tasks/
driver = hypertrack.Driver.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
driver.assign_tasks(task_ids=['6daacb03-6f02-4c60-b084-e9ffcd9eaf56', '37ae09b4-4801-48cb-bc50-99a7ee53f257'])

Example response

{

    "id": "6daacb03-6f02-4c60-b084-e9ffcd9eaf56",
    "driver_id": "c130a046-8b5a-4092-983b-f79aaedfe629",
    "status": "live",
    "started_at": "2016-10-26T10:12:57.730935Z",
    "ended_at": null,
    "vehicle_type": "motorcycle",
    "created_at": "2016-10-26T10:12:57.722382Z",
    "modified_at": "2016-10-27T13:01:35.435739Z",
    "has_ordered_tasks": true,
    "tasks": [
        {
            "id": "00c26b13-fcae-43af-91da-b0560898aa14",
            "trip_id": "6daacb03-6f02-4c60-b084-e9ffcd9eaf56",
            "destination": {
                "id": "8c918b2c-472d-4884-8e53-7a5b2772a95b",
                "customer": null,
                "address": "Apartment no. 3353, Grand Hyatt Residences",
                "landmark": "",
                "zip_code": "400055",
                "city": "Mumbai",
                "state": "Maharashtra",
                "country": "India",
                "location": {
                    "type": "Point",
                    "coordinates": [
                        72.8468571,
                        19.0803885
                    ]
                },
                "neighbourhood_id": null,
                "neighborhood_id": null,
                "created_at": "2016-08-09T09:13:01.208426Z",
                "modified_at": "2016-08-09T09:13:01.208479Z"
            },
            "action": "delivery",
            "status": "completed",
            "eta": "2016-08-12T12:52:16.509899Z",
            "initial_eta": "2016-08-12T12:52:16.509899Z",
            "committed_eta": "2016-08-12T12:45:00Z",
            "start_time": "2016-08-12T12:21:29.939000Z",
            "completion_time": "2016-08-12T13:18:07.114000Z",
            "completion_location": {
                "type": "Point",
                "coordinates": [
                    72.85100960000001,
                    19.078129499999996
                ]
            },
            "order_id": "495029",
            "connection_status": "connection_lost",
            "created_at": "2016-08-12T11:58:52.529652Z",
            "modified_at": "2016-08-12T13:18:19.639969Z",
            "last_heartbeat": "2016-08-21T16:05:04.188297Z",
            "tracking_url": "http://localhost:3000/bPt7oa",
            "group": "completed",
            "display": {
                "status": "completed",
                "sub_status": null,
                "status_text": "Completed",
                "sub_status_text": null,
                "show_summary": true,
                "sub_status_duration": null,
                "progress": 100,
                "duration_remaining": 0,
                "last_updated_at": "2016-08-12T13:18:07.114000Z"
            },
            "encoded_polyline": "}}isBqlo{L@b@@V??bKQ??Nu@?ABM?K?IA]AM??wACsCAsDDelAyhBzAcF?AAAAAACC?oBEE?A@C@A@ABAFAH?J?^@F@@@@@?R@hABH@??C@ABAB?BAL??qCE??CT??CfA??Y@??FiA??@W??V@??pCD??@M?C@C@CBA??IAiACSAA?AAAAAG?_@?K@I@G@C@ABA@AD?nBDB?@B@@@@?@Ar@?DA@ABCBA@QD??C@ABAB?BAL??qCE??WA??HoA??H{@XeC???ALaA??Ho@l@iEqNuE}@~B?@Uj@??gAk@mDgB??????",
            "time_aware_polyline": "",
            "distance": 4656
        },
      ],
    "eta": "2016-08-12T12:52:16.509899Z"
}

End Trip for a Driver

This API will end the live trip for a Driver.

HTTP Request

POST https://app.hypertrack.io/api/v1/drivers/<id>/end_trip/

Returns

Returns the Trip object that was ended.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://app.hypertrack.io/api/v1/drivers/d0ae4912-2074-45ef-a7c0-76be58639ea9/end_trip/
driver = hypertrack.Driver.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
driver.end_trip()

End Shift for a Driver

This API will end the live shift for a Driver.

HTTP Request

POST https://app.hypertrack.io/api/v1/drivers/<id>/end_trip/

Returns

Returns the Shift object which was ended.

curl -H "Authorization: token YOUR_SK_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     https://app.hypertrack.io/api/v1/drivers/d0ae4912-2074-45ef-a7c0-76be58639ea9/end_shift/
driver = hypertrack.Driver.retrieve('d0ae4912-2074-45ef-a7c0-76be58639ea9')
driver.end_shift()

results matching ""

    No results matching ""