Introduction

Welcome to the TriTrackers API. You can securely access your TriTrackers resources using traditional HTTP requests. Content uploaded to TriTrackers will be validated for integrity so that you can be sure we got every last bit.

TriTrackers API is organized around REST and uses HTTP verbs and response codes that most clients are familiar with. All requests must be formatted as Content-Type: application/json. All responses are also formatted JSON, encoded in the UTF-8 character encoding (Content-Type: application/json; charset=utf-8).

Authentication

This API uses OAuth2 authentication. Please contact support to request a developer API key.

Once supplied, the API key must be provided to all requests like follows.

Authorization: Bearer API_KEY_HERE

The bearer token is your key to accessing all of your resources via the TriTrackers API. Keep it safe.

Headers

Make sure you have the following content type headers are set on every request:

Accept: application/json Content-Type: application/json

URI

TriTrackers API is hosted on the following base URI:

https://tritrackers.com/api/v1

Errors

TriTrackers uses conventional HTTP response codes to indicate the success or failure of an API request. The table below contains a summary of the typical response codes:

Error Code	Meaning
200	Everything was ok.
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The resource requested is disabled.
404	Not Found -- The specified resource or endpoint could not be found.
405	Method Not Allowed.
422	The payload has missing required parameters or invalid data was given.
429	Too Many Requests.
500	Internal Server Error -- Request failed due to an internal error in TriTrackers.
503	Service Unavailable -- TriTrackers is temporarily offline for maintenance.

Data Units

Temperature data by default is displayed in Celsius. This can be updated to Fahrenheit through TriTrackers's user settings.

Speed and distance data are displayed in kilometers per hour and kilometers respectively. This can be updated to miles per hours and miles respectively through your TriTracker's user settings.

Devices

List Devices

{
    "devices": [
        {
            "id": "dl5001232-abc",
            "name": "DL5001232 - ABC",
            "type": "logger",
            "vehicle": "Mercedes Sprinter",
            "status": "active",
            "dates": {
                "min": "2019-01-15T22:00:00-08:00",
                "max": "2019-01-15T23:59:59-08:00"
            },
            "settings": {
                "gps": true
            },
            "dataLastReceivedAt": "2019-01-15T22:17:34-08:00",
            "registeredAt": "2019-01-11T10:57:34-08:00"
        },
        {
            "id": "dl5001247-xyz",
            "name": "DL5001247 - XYZ",
            "type": "logger",
            "vehicle": null,
            "status": "active",
            "dates": {
                "min": "2019-01-15T22:00:00-08:00",
                "max": "2019-01-15T23:59:59-08:00"
            },
            "settings": {
                "gps": true
            },
            "dataLastReceivedAt": "2019-01-15T22:23:01-08:00",
            "registeredAt": "2019-01-15T14:23:01-08:00"
        }
    ]
}

This endpoint retrieves all of your devices.

HTTP Request

GET /devices

Get Device

{
    "device": {
        "id": "dl5001247-xyz",
        "name": "DL5001247 - XYZ",
        "type": "logger",
        "vehicle": "Mercedes Sprinter",
        "status": "active",
        "dates": {
                "min": "2019-01-15T22:00:00-08:00",
                "max": "2019-01-15T23:59:59-08:00"
        },
        "settings": {
            "gps": true
        },
        "dataLastReceivedAt": "2019-01-15T22:23:01-08:00",
        "registeredAt": "2019-01-15T14:23:01-08:00"
    }
}

This endpoint retrieves a specific device.

HTTP Request

GET /devices/{id}

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID

Register Device

{
   "display_name": "DL5001247 - XYZ",
   "serial_number" : "XXXX-XXXX-XXXX-XXXX"
}

{
    "device": {
        "id": "dl5001247-xyz",
        "name": "DL5001247 - XYZ",
        "type": "logger",
        "vehicle": "Mercedes Sprinter",
        "status": "active",
        "dates": {
                "min": "2019-01-15T22:00:00-08:00",
                "max": "2019-01-15T23:59:59-08:00"
        },
        "settings": {
            "gps": true
        },
        "dataLastReceivedAt": "2019-01-15T22:23:01-08:00",
        "registeredAt": "2019-01-15T14:23:01-08:00"
    }
}

This endpoint register a new device to your account.

HTTP Request

POST /devices

Body Parameters

Name	Type	Required	Description
display_name	string	true	Name to be given to the device
serial_number	string	true	Serial Number that was provided upon purchase of the device

Update Device

{
    "display_name": "New Device Display Name",
    "vehicle_id" : 193
}

{
    "device": {
        "id": "dl5001247-xyz",
        "name": "New Device Display Name",
        "type": "logger",
        "vehicle": "Ford Transit",
        "status": "active",
        "dates": {
                "min": "2019-01-15T22:00:00-08:00",
                "max": "2019-01-15T23:59:59-08:00"
        },
        "settings": {
            "gps": true
        },
        "dataLastReceivedAt": "2019-01-15T22:23:01-08:00",
        "registeredAt": "2019-01-15T14:23:01-08:00"
    }
}

This endpoint updates your device.

HTTP Request

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID

PATCH /devices/{id}

Body Parameters

Name	Type	Required	Description
display_name	string	true	Name to be given to the device
vehicle_id	integer	false	Vehicle ID that should be assigned to the device

Devices Alarms

List Device Specific Alarms

{
    "alarms": [
        {
            "id": 137,
            "name": "Box Temperature Zone 0",
            "type": 3,
            "description": "Box Temperature Zone 0 : 0 °C",
            "latitude": 49.05,
            "longitude": -123.06,
            "value": "0 °C",
            "range": "out",
            "currentSettings": null,
            "timestamp": "2019-01-11T09:30:03-08:00"
        },
        {
            "id": 158,
            "name": "System Voltage",
            "type": 1,
            "description": "System Voltage : 11.5 V",
            "latitude": 49.05,
            "longitude": -123.06,
            "value": "11.5 V",
            "range": "out",
            "currentSettings": {
                "max": 15,
                "min": 11,
                "state": true
            },
            "timestamp": "2019-01-07T14:11:33-08:00"
        }
    ]
}

This endpoint retrieves all of a specific devices alarms that have been triggered.

HTTP Request

GET /devices/{id}/alarms

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID

Devices GPS

List Devices' GPS

{
    "gpsDevices": [
        {
            "id": "dl5001247-abc",
            "name": "DL5001247 - ABC",
            "type": "logger",
            "latestData": {
                "coordinates": {
                    "latitude": 34.05,
                    "longitude": 118.24
                },
                "systemVoltage": 13.3,
                "ambientTemperature": 9.9,
                "boxTemperature": 3.1,
                "timestamp": "2019-01-11T17:57:00-08:00"
            }
        },
        {
            "id": "dl5001247-xyz",
            "name": "DL5001247 - XYZ",
            "type": "logger",
            "latestData": {
                "coordinates": {
                    "latitude": 49.16,
                    "longitude": 123.07
                },
                "systemVoltage": 13.2,
                "ambientTemperature": 13.7,
                "boxTemperature": 12.8,
                "timestamp": "2019-01-15T20:23:00-08:00"
            }
        }
    ]
}

This endpoint retrieves all of your devices' most recent GPS data.

HTTP Request

GET /devices/gps/current

Get Device Specific GPS Data

{
    "data": [
        {
            "coordinates": {
                "latitude": 49.18,
                "longitude": -122.96
            },
            "speed": 68.5,
            "timestamp": "2019-01-10T07:12:00-08:00"
        },
        {
            "coordinates": {
                "latitude": 49.16,
                "longitude": -122.94
            },
            "speed": 72,
            "timestamp": "2019-01-10T07:14:00-08:00"
        }
    ],
    "statistics": {
        "time": "2019-01-10T07:14:00-08:00",
        "totalDistance": 2.3,
        "averageSpeed": 70.25,
        "numberOfDoorOpenings": 1,
        "numberOfStops": 1
    }
}

This endpoint retrieves all of a specific device's GPS data for a given datetime range.

HTTP Request

GET /devices/{id}/gps?start_date={start_date}&end_date={end_date}

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID
start_date	string	true	UNIX Epoch time to begin retrieving GPS data by. This must be within twenty four hours of the end_date.
end_date	string	true	UNIX Epoch time to stop retrieving GPS data by. This must be within twenty four hours of the start_date.

To view and convert ISO8601 strings to UNIX Epoch time, reference Epoch Time Converter or a similar tool. For example, 2019-01-10T08:13:00-08:00 converts to 1547136780 (seconds since epoch)

Devices Events

Get Device Specific Events data

{
    "events": [
        {
            "coordinates": {
                "latitude": 49.16,
                "longitude": 123.07
            },
            "duration": "3 minutes",
            "timestamp": "2019-01-14T16:00:00-08:00"
        },
        {
            "coordinates": {
                "latitude": 49.16,
                "longitude": 123.07
            },
            "duration": "63 minutes",
            "timestamp": "2019-01-15T05:00:00-08:00"
        }
    ],
    "name": "door-openings"
}

This endpoint retrieves all of a specific device's events data for a given datetime range.

HTTP Request

GET /devices/{id}/events/{event_name}?start_date={start_date}&end_date={end_date}

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID
event_name	string	true	Event name to retrieve data for. This must be either `stops` or `door-openings`
start_date	string	true	UNIX Epoch time to begin retrieving events data by. This must be within twenty four hours of the end_date.
end_date	string	true	UNIX Epoch time to stop retrieving events data by. This must be within twenty four hours of the start_date.

To view and convert ISO8601 strings to UNIX Epoch time, reference Epoch Time Converter or a similar tool. For example, 2019-01-10T08:13:00-08:00 converts to 1547136780 (seconds since epoch)

Devices Temperature Sensors

Get Device Specific Temperature Sensors data

{
    "data": [
        {
            "ambientTemperature": 47.66,
            "box1Temperature": 50.54,
            "box2Temperature": 50.72,
            "evaporatorTemperature": 49.64,
            "gps": {
                "latitude": 49.05,
                "longitude": -123.06,
                "speed": 74.3
            },
            "timestamp": "2019-01-10T08:03:00-08:00"
        },
        {
            "ambientTemperature": 47.48,
            "box1Temperature": 51.26,
            "box2Temperature": 52.52,
            "evaporatorTemperature": 49.82,
            "gps": {
                "latitude": 49.09,
                "longitude": -122.93,
                "speed": 87.4
            },
            "timestamp": "2019-01-10T08:13:00-08:00"
        },
        {
            "ambientTemperature": 48.2,
            "box1Temperature": 51.98,
            "box2Temperature": 53.96,
            "evaporatorTemperature": 50.72,
            "gps": {
                "latitude": 49.05,
                "longitude": -122.8,
                "speed": 43.3
            },
            "timestamp": "2019-01-10T08:23:00-08:00"
        }
    ]
}

This endpoint retrieves all of a specific device's temperature sensors data for a given datetime range.

HTTP Request

GET /devices/{id}/data/temperature?start_date={start_date}&end_date={end_date}

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID
start_date	string	true	UNIX Epoch time to begin retrieving events data by. This must be within twenty four hours of the end_date.
end_date	string	true	UNIX Epoch time to stop retrieving events data by. This must be within twenty four hours of the start_date.

To view and convert ISO8601 strings to UNIX Epoch time, reference Epoch Time Converter or a similar tool. For example, 2019-01-10T08:13:00-08:00 converts to 1547136780 (seconds since epoch)

Devices Health Sensors

Get Device Specific Health Sensors Data

{
    "data": [
        {
            "systemVoltage": 13.1,
            "runTime": 0,
            "current1": -0.4,
            "current2": 0,
            "current3": -0.1,
            "current4": -0.2,
            "pressure": 0,
            "gps": {
                "latitude": 49.05,
                "longitude": -123.06,
                "speed": 74.3
            },
            "timestamp": "2019-01-10T08:03:00-08:00"
        },
        {
            "systemVoltage": 13.1,
            "runTime": 0,
            "current1": -0.3,
            "current2": 0,
            "current3": -0.1,
            "current4": -0.2,
            "pressure": 0,
            "gps": {
                "latitude": 49.09,
                "longitude": -122.93,
                "speed": 87.4
            },
            "timestamp": "2019-01-10T08:13:00-08:00"
        },
        {
            "systemVoltage": 13.1,
            "runTime": 0,
            "current1": -0.4,
            "current2": 0,
            "current3": -0.1,
            "current4": -0.2,
            "pressure": 0,
            "gps": {
                "latitude": 49.05,
                "longitude": -122.8,
                "speed": 43.3
            },
            "timestamp": "2019-01-10T08:23:00-08:00"
        }
    ]
}

This endpoint retrieves all of a specific device's health sensors data for a given datetime range.

HTTP Request

GET /devices/{id}/data/health?start_date={start_date}&end_date={end_date}

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID
start_date	string	true	UNIX Epoch time to begin retrieving events data by. This must be within twenty four hours of the end_date.
end_date	string	true	UNIX Epoch time to stop retrieving events data by. This must be within twenty four hours of the start_date.

To view and convert ISO8601 strings to UNIX Epoch time, reference Epoch Time Converter or a similar tool. For example, 2019-01-10T08:13:00-08:00 converts to 1547136780 (seconds since epoch)

Devices Initializations

Get Device Specific Initialization Data

{
    "initializations": [
        {
            "id": 207,
            "type": "alarm",
            "name": "system_voltage",
            "zone": null,
            "settings": {
                "max": 15,
                "min": 11,
                "state": true
             },
            "status": "Processed",
            "lastSetAt": "2019-01-06T13:05:55-08:00",
            "lastProcessedAt": "2019-01-06T13:05:55-08:00"
        },
        {
            "id": 231,
            "type": "control",
            "name": "unit_control",
            "zone": 0,
            "settings": {
                "mode": "cooling",
                "state": true,
                "temperature": -20
            },
            "status": "Processed",
            "lastSetAt": "2019-01-10T09:05:55-08:00",
            "lastProcessedAt": "2019-01-10T09:05:55-08:00"
        }
    ]
}

This endpoint retrieves all of a specific device's initializations data.

HTTP Request

GET /devices/{id}/initializations

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID

Get Specific Initialization Data

{
    "initialization": {
        "id": 207,
        "type": "control",
        "name": "unit_control",
        "zone": 0,
        "settings": {
            "mode": "cooling",
            "state": true,
            "temperature": -20
        },
        "status": "Processed",
        "lastSetAt": "2019-01-06T13:05:55-08:00",
        "lastProcessedAt": "2019-01-06T13:05:55-08:00"
    }
}

This endpoint retrieves a device's specific initialization.

HTTP Request

GET devices/{id}/initializations/{initialization_id}

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID
initialization_id	string	true	Initialization ID

Set Alarm Initialization

{
    "name": "box_temperature",
    "state" : true,
    "zone" : 0,
    "min" : -20,
    "max" : 20
}

{
    "initialization": {
        "id": 240,
        "type": "alarm",
        "name": "box_temperature",
        "zone": 0,
        "settings": {
                "max": 20,
                "min": -20,
                "state": true
        },
        "status": "Pending",
        "lastSetAt": "2019-01-12T13:05:55-08:00",
        "lastProcessedAt": null
    }
}

This endpoint sets a device alarm initialization.

HTTP Request

POST /devices/{id}/initialization

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID

Body Parameters

Name	Type	Required	Description
name	string	true	Name of the initialization to set (system_voltage or box_temperature)
state	boolean	true	Represents whether or not the initialization is toggled on or off
zone	integer	with box_temperature	Zone to set the alarm for (0 or 1)
min	float	true	Minimum value of the alarm range.
max	float	true	Maximum value of the alarm range.

Set Unit Control Initialization

{
    "name": "unit_control",
    "state" : true,
    "zone": 0,
    "mode" : "cooling",
    "temperature": -20
}

{
    "initialization": {
        "id": 207,
        "type": "control",
        "name": "unit_control",
        "zone": 0,
        "settings": {
            "mode": "cooling",
            "state": true,
            "temperature": -20
        },
        "status": "Processed",
        "lastSetAt": "2019-01-06T13:05:55-08:00",
        "lastProcessedAt": "2019-01-06T13:05:55-08:00"
    }
}

This endpoint sets a device unit control initialization.

HTTP Request

POST /devices/{id}/initialization

URL Parameters

Name	Type	Required	Description
id	string	true	Device ID

Body Parameters

Name	Type	Required	Description
name	string	true	Name of the initialization to set (unit_control)
state	boolean	true	Represents whether or not the initialization is toggled on or off
zone	integer	with box_temperature	Zone to set the alarm for (0 or 1)
mode	string	true	Represents whether the control is for heating or cooling.
temperature	float	true	Temperature to set.

Resource Definitions

Devices

Property	Type	Description
id	integer	Device ID
name	string	Device name
type	string	Device type. Includes logger, single_controller and dual_controller
vehicle	string	Vehicle name that the device is attached to
status	string	Indicates whether the device is active or inactive
dates.min	string	Datetime the device available to query data from
dates.max	string	Datetime the device is available to query data to
settings.gps	boolean	Indicates whether the device has gps enabled or disabled
dataLastReceivedAt	string	Last datetime data was recorded at
registeredAt	string	Datetime the device was attached to the user's account

Devices Alarms

Property	Type	Description
id	integer	Alarm ID
name	string	Alarm name. Includes system_voltage and box_temperature
type	integer	Denotes the alarm name and range. 0 and 1 are system voltage (in and out of range), 2 and 3 are box temperature zone 0 (in and out of range), 4 and 5 are box temperature zone 1 (in and out of range)
description	string	Alarm name and corresponding value
latitude	float	Latitude the alarm occurred at
longitude	float	Longitude the alarm occurred at
value	string	Float and measurement the alarm occurred at
range	string	Indicates if the alarm came in our out of range
currentSettings.max	float	Maximum range for the alarm
currentSettings.min	float	Minimum range for the alarm
currentSettings.state	boolean	Indicates whether the alarm is on or off, where true is on and false is off

Devices GPS

List Devices' GPS

Property	Type	Description
id	integer	Device ID
name	string	Device name
type	string	Device type. Includes logger, single_controller and dual_controller
latestData.coordinates.latitude	float	Device's latest latitude
latestData.coordinates.longitude	float	Device's latest longitude
latestData.systemVoltage	float	System voltage of the reefer unit
latestData.ambientTemperature	float	Ambient temperature of the reefer unit
latestData.boxTemperature	float	Temperature of the reefer unit's box
latestData.timestamp	string	Last datetime data was recorded at

Get Device Specific GPS Data

Property	Type	Description
id	integer	Device ID
coordinates.latitude	float	Latitude for the specified timestamp
coordinates.longitude	float	Longitude for the specified timestamp
speed	float	Speed in kilometers per hour at the specified timestamp
timestamp	string	Datetime the data was recorded at
statistics.time	string	Last datetime data recorded at for all of the given GPS data in the datetime range
statistics.totalDistance	float	Total distance travelled in kilometers
statistics.average	float	Average speed in kilometers per hour
statistics.numberOfDoorOpenings	integer	Number of times the reefer unit's door was opened
statistics.numberOfStops	integer	Number of times the vehicle stopped

Devices Events

Property	Type	Description
name	string	Name of the event. Includes door-openings and stops
latitude	float	Latitude for the specified timestamp
longitude	float	Longitude for the specified timestamp the alarm occurred at
duration	string	Length of the event in minutes
timestamp	string	Datetime the data was recorded at

Devices Temperature Sensors

Property	Type	Description
ambientTemperature	float	Ambient temperature of the reefer unit
box1Temperature	float	Temperature of the back (by the door) of the reefer unit's box
box2Temperature	float	Temperature of the front (by the cab) of the reefer unit's box
evaporatorTemperature	float	Temperature of the reefer unit's evaporator
gps.latitude	float	Latitude for the specified timestamp
gps.longitude	float	Longitude for the specified timestamp
gps.duration	string	Length of the event in minutes
speed	float	Speed in kilometers per hour at the specified timestamp
timestamp	string	Datetime the data was recorded at

Devices Health Sensors

Property	Type	Description
systemVoltage	float	System Voltage of the reefer unit
runTime	float	Voltage Counter of the reefer unit
current1	float	Current1 of the reefer unit
current2	float	Current2 of the reefer unit
current3	float	Current3 of the reefer unit
current4	float	Current4 of the reefer unit
pressure	float	Pressure of the reefer unit
gps.latitude	float	Latitude for the specified timestamp
gps.longitude	float	Longitude for the specified timestamp
gps.speed	float	Speed in kilometers per hour at the specified timestamp
timestamp	string	Datetime the data was recorded at

Devices Initializations

Property	Type	Description
id	integer	Initialization ID
type	string	Initialization type. Includes alarm and control.
name	string	Name of the initialization. Includes system_voltage, box_temperature and unit_control
settings.zone	integer	Zone to set an initialization (box_temperature and unit_control) for. Includes 0 and 1. 0 being the back of the reefer unit (by the door), 1 being the front of the reefer unit (by the cab)
settings.state	boolean	Indicates whether to turn an initialization on or off, where true is on and false is off
settings.mode	string	Represents whether the control is for heating or cooling.
settings.temperature	float	Temperature to set a control initialization at
settings.max	float	Maximum range for an alarm initialization
settings.min	float	Minimum range for an alarm initialization
status	string	Indicates if the initialization was success or not. Includes Processed and Pending
lastSetAt	string	Datetime the initialization was last set at
lastProcessedAt	string	Datetime the initialization was last processed at (successfully set)