Starting from version 3.0 Data Trak Tracking server includes web API to access GPS tracking data from your own applications. Version 3.3 and all later versions are using REST API. Documentation for the API can be found in the swagger.json file and API Reference. There are a lot of tools available to automatically generate client from Swagger format. For more information about Swagger see official website – http://swagger.io/.
There are two authorization options:
- Using session cookies (see “session” URL path)
- Standard HTTP authorization header
View API documentation:
Access token
As an alternative to email and password login, there is an option to use account token for authorization. Token can be set in the corresponding field of the user model. Token can only be used to create a session. It can not be used for basic authorization option.
To create a token use “token” query parameter in session get request:
/api/session?token=USER_TOKEN
WebSocket API
In addition to Data Trak REST API, we provide access to a WebSocket endpoint for live location updates and events. URL for the connection:
/api/socket
Session cookie is the only authorization option for WebSocket connection.
Each message in WebSocket communication uses same universal JSON format:
{
"devices": [...],
"positions: [...],
"events": [...]
}
Each array contains corresponding standard models:
If message does not contain objects of one of the types, the key would not be included in the JSON structure. Most of the time messages contain a single type of objects.
Tracking
Base URL: /api, Version: 4.2
Summary
| Path | Operation | Description |
|---|---|---|
| /attributes/computed | GET | Fetch a list of Attributes |
| POST | Create an Attribute | |
| /attributes/computed/{id} | DELETE | Delete an Attribute |
| PUT | Update an Attribute | |
| /calendars | GET | Fetch a list of Calendars |
| POST | Create a Calendar | |
| /calendars/{id} | DELETE | Delete a Calendar |
| PUT | Update a Calendar | |
| /commands | GET | Fetch a list of Saved Commands |
| POST | Create a Saved Command | |
| /commands/send | GET | Fetch a list of Saved Commands supported by Device at the moment |
| POST | Dispatch commands to device | |
| /commands/types | GET | Fetch a list of available Commands for the Device or all possible Commands if Device ommited |
| /commands/{id} | DELETE | Delete a Saved Command |
| PUT | Update a Saved Command | |
| /devices | GET | Fetch a list of Devices |
| POST | Create a Device | |
| /devices/{id} | DELETE | Delete a Device |
| PUT | Update a Device | |
| /devices/{id}/accumulators | PUT | Update total distance and hours of the Device |
| /drivers | GET | Fetch a list of Drivers |
| POST | Create a Driver | |
| /drivers/{id} | DELETE | Delete a Driver |
| PUT | Update a Driver | |
| /events/{id} | GET | |
| /geofences | GET | Fetch a list of Geofences |
| POST | Create a Geofence | |
| /geofences/{id} | DELETE | Delete a Geofence |
| PUT | Update a Geofence | |
| /groups | GET | Fetch a list of Groups |
| POST | Create a Group | |
| /groups/{id} | DELETE | Delete a Group |
| PUT | Update a Group | |
| /maintenance | GET | Fetch a list of Maintenance |
| POST | Create a Maintenance | |
| /maintenance/{id} | DELETE | Delete a Maintenance |
| PUT | Update a Maintenance | |
| /notifications | GET | Fetch a list of Notifications |
| POST | Create a Notification | |
| /notifications/test | POST | Send test notification to current user via Email and SMS |
| /notifications/types | GET | Fetch a list of available Notification types |
| /notifications/{id} | DELETE | Delete a Notification |
| PUT | Update a Notification | |
| /permissions | DELETE | Unlink an Object from another Object |
| POST | Link an Object to another Object | |
| /positions | GET | Fetches a list of Positions |
| /reports/events | GET | Fetch a list of Events within the time period for the Devices or Groups |
| /reports/route | GET | Fetch a list of Positions within the time period for the Devices or Groups |
| /reports/stops | GET | Fetch a list of ReportStops within the time period for the Devices or Groups |
| /reports/summary | GET | Fetch a list of ReportSummary within the time period for the Devices or Groups |
| /reports/trips | GET | Fetch a list of ReportTrips within the time period for the Devices or Groups |
| /server | GET | Fetch Server information |
| PUT | Update Server information | |
| /session | DELETE | Close the Session |
| GET | Fetch Session information | |
| POST | Create a new Session | |
| /statistics | GET | Fetch server Statistics |
| /users | GET | Fetch a list of Users |
| POST | Create a User | |
| /users/{id} | DELETE | Delete a User |
| PUT | Update a User |
Security
basicAuth
Type: basic
- Description:
-
Basic HTTP authorization with email and password
Paths
GET /attributes/computed
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
| deviceId | Standard users can use this only with _deviceId_s, they have access to | query | integer | #/parameters/deviceId |
| groupId | Standard users can use this only with _groupId_s, they have access to | query | integer | #/parameters/groupId |
| refresh | query | boolean | #/parameters/refresh |
- 200 OK
-
OK
POST /attributes/computed
| body | body | object | #/parameters/Attribute |
- 200 OK
-
OK
DELETE /attributes/computed/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /attributes/computed/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Attribute |
- 200 OK
-
OK
GET /calendars
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
- 200 OK
-
OK
POST /calendars
| body | body | object | #/parameters/Calendar |
- 200 OK
-
OK
DELETE /calendars/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /calendars/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Calendar |
- 200 OK
-
OK
GET /commands
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
| deviceId | Standard users can use this only with _deviceId_s, they have access to | query | integer | #/parameters/deviceId |
| groupId | Standard users can use this only with _groupId_s, they have access to | query | integer | #/parameters/groupId |
| refresh | query | boolean | #/parameters/refresh |
- 200 OK
-
OK
POST /commands
| body | body | object | #/parameters/Command |
- 200 OK
-
OK
GET /commands/send
| deviceId | Standard users can use this only with _deviceId_s, they have access to | query | integer | #/parameters/deviceId |
- 200 OK
-
OK
- 400 Bad Request
-
Could happen when the user doesn’t have permission for the device
POST /commands/send
- 200 OK
-
Command sent
- 202 Accepted
-
Command queued
- 400 Bad Request
-
Could happen when the user doesn’t have permission or an incorrect command type for the device
GET /commands/types
| deviceId | query | integer | ||
| textChannel | query | boolean |
- 200 OK
-
OK
- 400 Bad Request
-
Could happen when trying to fetch from a device the user does not have permission
DELETE /commands/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /commands/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Command |
- 200 OK
-
OK
GET /devices
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
| id | To fetch one or more devices. Multiple params can be passed like id=31&id=42 |
query | integer , multiple parameters (id=aaa&id=bbb) |
|
| uniqueId | To fetch one or more devices. Multiple params can be passed like uniqueId=333331&uniqieId=44442 |
query | string , multiple parameters (uniqueId=aaa&uniqueId=bbb) |
- 200 OK
-
OK
- 400 Bad Request
-
No permission
POST /devices
| body | body | object | #/parameters/Device |
- 200 OK
-
OK
DELETE /devices/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /devices/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Device |
- 200 OK
-
OK
PUT /devices/{id}/accumulators
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
GET /drivers
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
| deviceId | Standard users can use this only with _deviceId_s, they have access to | query | integer | #/parameters/deviceId |
| groupId | Standard users can use this only with _groupId_s, they have access to | query | integer | #/parameters/groupId |
| refresh | query | boolean | #/parameters/refresh |
- 200 OK
-
OK
POST /drivers
| body | body | object | #/parameters/Driver |
- 200 OK
-
OK
DELETE /drivers/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /drivers/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Driver |
- 200 OK
-
OK
GET /events/{id}
| id | path | integer | #/parameters/entityId |
- 200 OK
-
OK
GET /geofences
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
| deviceId | Standard users can use this only with _deviceId_s, they have access to | query | integer | #/parameters/deviceId |
| groupId | Standard users can use this only with _groupId_s, they have access to | query | integer | #/parameters/groupId |
| refresh | query | boolean | #/parameters/refresh |
- 200 OK
-
OK
POST /geofences
| body | body | object | #/parameters/Geofence |
- 200 OK
-
OK
DELETE /geofences/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /geofences/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Geofence |
- 200 OK
-
OK
GET /groups
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
- 200 OK
-
OK
POST /groups
| body | body | object | #/parameters/Group |
- 200 OK
-
OK
- 400 Bad Request
-
No permission
DELETE /groups/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /groups/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Group |
- 200 OK
-
OK
GET /maintenance
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
| deviceId | Standard users can use this only with _deviceId_s, they have access to | query | integer | #/parameters/deviceId |
| groupId | Standard users can use this only with _groupId_s, they have access to | query | integer | #/parameters/groupId |
| refresh | query | boolean | #/parameters/refresh |
- 200 OK
-
OK
POST /maintenance
| body | body | object | #/parameters/Maintenance |
- 200 OK
-
OK
DELETE /maintenance/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /maintenance/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Maintenance |
- 200 OK
-
OK
GET /notifications
| all | Can only be used by admins or managers to fetch all entities | query | boolean | #/parameters/all |
| userId | Standard users can use this only with their own userId | query | integer | #/parameters/userId |
| deviceId | Standard users can use this only with _deviceId_s, they have access to | query | integer | #/parameters/deviceId |
| groupId | Standard users can use this only with _groupId_s, they have access to | query | integer | #/parameters/groupId |
| refresh | query | boolean | #/parameters/refresh |
- 200 OK
-
OK
POST /notifications
| body | body | object | #/parameters/Notification |
- 200 OK
-
OK
POST /notifications/test
- 204 No Content
-
Successful sending
- 400 Bad Request
-
Could happen if sending has failed
GET /notifications/types
- 200 OK
-
OK
DELETE /notifications/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /notifications/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/Notification |
- 200 OK
-
OK
DELETE /permissions
| body | body | object | #/parameters/Permission |
- 204 No Content
-
No Content
POST /permissions
| body | body | object | #/parameters/Permission |
- 200 OK
-
OK
- 400 Bad Request
-
No permission
GET /positions
| deviceId | deviceId is optional, but requires the from and _to_ parameters when used | query | integer | |
| from | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | |
| to | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | |
| id | To fetch one or more positions. Multiple params can be passed like id=31&id=42 |
query | integer , multiple parameters (id=aaa&id=bbb) |
- 200 OK
-
OK
GET /reports/events
| deviceId | query | integer[] , multiple parameters (deviceId=aaa&deviceId=bbb) |
#/parameters/deviceIdArray | |
| groupId | query | integer[] , multiple parameters (groupId=aaa&groupId=bbb) |
#/parameters/groupIdArray | |
| type | % can be used to return events of all types | query | string[] | |
| from | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/fromTime |
| to | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/toTime |
- 200 OK
-
OK
GET /reports/route
| deviceId | query | integer[] , multiple parameters (deviceId=aaa&deviceId=bbb) |
#/parameters/deviceIdArray | |
| groupId | query | integer[] , multiple parameters (groupId=aaa&groupId=bbb) |
#/parameters/groupIdArray | |
| from | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/fromTime |
| to | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/toTime |
- 200 OK
-
OK
GET /reports/stops
| deviceId | query | integer[] , multiple parameters (deviceId=aaa&deviceId=bbb) |
#/parameters/deviceIdArray | |
| groupId | query | integer[] , multiple parameters (groupId=aaa&groupId=bbb) |
#/parameters/groupIdArray | |
| from | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/fromTime |
| to | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/toTime |
- 200 OK
-
OK
GET /reports/summary
| deviceId | query | integer[] , multiple parameters (deviceId=aaa&deviceId=bbb) |
#/parameters/deviceIdArray | |
| groupId | query | integer[] , multiple parameters (groupId=aaa&groupId=bbb) |
#/parameters/groupIdArray | |
| from | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/fromTime |
| to | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/toTime |
- 200 OK
-
OK
GET /reports/trips
| deviceId | query | integer[] , multiple parameters (deviceId=aaa&deviceId=bbb) |
#/parameters/deviceIdArray | |
| groupId | query | integer[] , multiple parameters (groupId=aaa&groupId=bbb) |
#/parameters/groupIdArray | |
| from | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/fromTime |
| to | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/toTime |
- 200 OK
-
OK
GET /server
- 200 OK
-
OK
PUT /server
- 200 OK
-
OK
DELETE /session
- 204 No Content
-
No Content
GET /session
| token | query | string |
- 200 OK
-
OK
- 404 Not Found
-
Not Found
POST /session
| formData | string | |||
| password | formData | string (password) |
- 200 OK
-
OK
- 401 Unauthorized
-
Unauthorized
GET /statistics
| from | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/fromTime |
| to | in IS0 8601 format. eg. 1963-11-22T18:30:00Z |
query | string (date-time) | #/parameters/toTime |
- 200 OK
-
OK
GET /users
| userId | Can only be used by admin or manager users | query | string |
- 200 OK
-
OK
- 400 Bad Request
-
No Permission
POST /users
| body | body | object | #/parameters/User |
- 200 OK
-
OK
DELETE /users/{id}
| id | path | integer | #/parameters/entityId |
- 204 No Content
-
No Content
PUT /users/{id}
| id | path | integer | #/parameters/entityId | |
| body | body | object | #/parameters/User |
- 200 OK
-
OK
Parameter definitions
Schema definitions
- id: integer
- description: string
- attribute: string
- expression: string
- type: string
- String|Number|Boolean
- id: integer
- name: string
- data: string
- base64 encoded in iCalendar format
- atributes: object
- id: integer
- name: string
- uniqueId: string
- status: string
- disabled: boolean
- lastUpdate: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - positionId: integer
- groupId: integer
- phone: string
- model: string
- contact: string
- category: string
- geofenceIds: integer[]
-
integer - attributes: object
- id: integer
- type: string
- serverTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - deviceId: integer
- positionId: integer
- geofenceId: integer
- maintenanceId: integer
- attributes: object
- id: integer
- name: string
- description: string
- area: string
- calendarId: integer
- attributes: object
- id: integer
- name: string
- type: string
- start: number
- period: number
- atributes: object
- id: integer
- type: string
- always: boolean
- web: boolean
- mail: boolean
- sms: boolean
- calendarId: integer
- attributes: object
- userId: integer
- User Id, can be only first parameter
- deviceId: integer
- Device Id, can be first parameter or second only in combination with userId
- groupId: integer
- Group Id, can be first parameter or second only in combination with userId
- geofenceId: integer
- Geofence Id, can be second parameter only
- calendarId: integer
- Geofence Id, can be second parameter only and only in combination with userId
- attributeId: integer
- Computed Attribute Id, can be second parameter only
- driverId: integer
- Driver Id, can be second parameter only
- managedUserId: integer
- User Id, can be second parameter only and only in combination with userId
- id: integer
- deviceId: integer
- protocol: string
- deviceTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - fixTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - serverTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - outdated: boolean
- valid: boolean
- latitude: number
- longitude: number
- altitude: number
- speed: number
- in knots
- course: number
- address: string
- accuracy: number
- network: string
- attributes: object
- deviceId: integer
- deviceName: string
- duration: integer
- startTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - address: string
- lat: number
- lon: number
- endTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - spentFuel: number
- in liters
- engineHours: integer
- deviceId: integer
- deviceName: string
- maxSpeed: number
- in knots
- averageSpeed: number
- in knots
- distance: number
- in meters
- spentFuel: number
- in liters
- engineHours: integer
- deviceId: integer
- deviceName: string
- maxSpeed: number
- in knots
- averageSpeed: number
- in knots
- distance: number
- in meters
- spentFuel: number
- in liters
- duration: integer
- startTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - startAddress: string
- startLat: number
- startLon: number
- endTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - endAddress: string
- endLat: number
- endLon: number
- driverUniqueId: integer
- driverName: string
- id: integer
- registration: boolean
- readonly: boolean
- deviceReadonly: boolean
- limitCommands: boolean
- map: string
- bingKey: string
- mapUrl: string
- poiLayer: string
- latitude: number
- longitude: number
- zoom: integer
- twelveHourFormat: boolean
- version: string
- forceSettings: boolean
- coordinateFormat: string
- attributes: object
- captureTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - activeUsers: integer
- activeDevices: integer
- requests: integer
- messagesReceived: integer
- messagesStored: integer
- id: integer
- name: string
- email: string
- readonly: boolean
- administrator: boolean
- map: string
- latitude: number
- longitude: number
- zoom: integer
- password: string
- twelveHourFormat: boolean
- coordinateFormat: string
- disabled: boolean
- expirationTime: string (date-time)
- in IS0 8601 format. eg.
1963-11-22T18:30:00Z - deviceLimit: integer
- userLimit: integer
- deviceReadonly: boolean
- limitCommands: boolean
- poiLayer: string
- token: string
- attributes: object