This document gives you all the information necessary to connect external services with our system and send or gather DRIVER data.
Our DRIVER API offers a set of callable methods that you can send requests to. The request type required depends on the method called and is therefore documented specifically for each method. Request parameters must be sent as JSON encoded object (where applicable).
As response you will get a JSON encoded object. In case of a non-successful response, you will get an HTTP error response code and an error message.
The timezone used is the local timezone of the authenticated user.
All requests to the API must contain an Authorization header. The Authorization header holds either a user token or a driver token, depending on the method called. These tokens are used to identify your user account or a specific driver account.
Please log in to see your personal user token here.
Please make sure that your tokens are handled with care. In case your tokens have been compromised, contact us immediately.
Note: As the API is optimised for performance, driver permissions granted through the platform are not taken into account by the API. Therefore, please always use the API token of the user account that owns the relevant entities (drivers) (i.e. the user account which can grant permissions to other users).
The response will have different HTTP response codes set, based on whether the request has been successful or not. The possible values are:
code 200 (OK) code 400 (Bad Request) code 401 (Unauthorized) code 405 (Method Not Allowed) code 500 (Internal Server Error)
In case of an error you will find further details in the message node of the JSON object.
API endpoint: https://www.gps365.at/api_driver/drivers Request type: GET Authorization: user [USER_TOKEN, e.g. 392ea8428d10b0392c399c93810045a9]
Returns a list of all active drivers belonging to the given user.
Request example
curl -X GET https://www.gps365.at/api_driver/drivers \
-H "Authorization: user 392ea8428d10b0392c399c93810045a9"
Response example
(HTTP response code: 200 OK)
[
{
"id": 1,
"name": "Maximilian Muster",
"description": null,
"group": "Fahrer",
"driver_token": "1ad35ddc5934cff26c650c7e8d28a395"
},
{
"id": 2,
"name": "Theresa Test",
"description": null,
"group": "Fahrer",
"driver_token": "ea18e34fdad2e7df67bff06d4025173c"
},
[...]
]
Response data
| Field | Description |
|---|---|
| id | The unique ID of the driver which is immutable. |
| name | The name of the driver which can be edited by the user. |
| description | The description of the driver which can be edited by the user. It is an optional field and thus can be null. |
| group | The group of the driver which can be edited by the user. |
| driver_token | The driver token needed to call methods which are based on a specific driver. |
API endpoint: https://www.gps365.at/api_driver/drivers/all Request type: GET Authorization: user [USER_TOKEN, e.g. 392ea8428d10b0392c399c93810045a9]
Returns a list of all drivers (active and archived) belonging to the given user. This endpoint equals "4.1. List drivers" but also returns archived drivers. The Response data has an additional boolean field `archived` to distinguish between active and archived drivers.
Please note that it is not possible to retrieve data from the endpoints "5. Account" and "6. Workdays" for archived drivers.
Request example
curl -X GET https://www.gps365.at/api_driver/drivers/all \
-H "Authorization: user 392ea8428d10b0392c399c93810045a9"
Response example
(HTTP response code: 200 OK)
[
{
"id": 1,
"name": "Maximilian Muster",
"description": null,
"group": "Fahrer",
"driver_token": "1ad35ddc5934cff26c650c7e8d28a395",
"archived": false
},
{
"id": 2,
"name": "Theresa Test",
"description": null,
"group": "Fahrer",
"driver_token": "ea18e34fdad2e7df67bff06d4025173c",
"archived": true
},
[...]
]
Response data
Format of response data equals the one described at "4.1. List drivers" with one additional field:
| Field | Description |
|---|---|
| archived | Boolean field which determines whether or not the driver is archived. |
API endpoint: https://www.gps365.at/api_driver/account/details Request type: GET Authorization: driver [DRIVER_TOKEN, e.g. 1ad35ddc5934cff26c650c7e8d28a395]
Returns all account details about the given driver incl. available time categories, currently active time category and tracker.
Request example
curl -X GET https://www.gps365.at/api_driver/account/details \
-H "Authorization: driver 1ad35ddc5934cff26c650c7e8d28a395"
Response example
(HTTP response code: 200 OK)
{
"mode": "qr",
"name": "Maximilian Muster",
"categories": {
"drive": {
"title": "Lenkzeit",
"subcategories": [],
"icon": "drive",
"selectable": false
},
"standby": {
"title": "Lenkpause (Arbeitsbereitschaft)",
"subcategories": [],
"icon": "standby",
"selectable": true
},
"work": {
"title": "Sonstige Arbeitszeit",
"subcategories": {
"3c16d5": "Büroarbeit",
"f06c70": "Lagerarbeit",
"6d0e53": "Sonstiges"
},
"icon": "work",
"selectable": true
},
"rest": {
"title": "Ruhezeit",
"subcategories": [],
"icon": "rest",
"selectable": true
}
},
"category": {
"category": "drive",
"subcategory": "",
"duration": 360,
"tracker": {
"title": "Beispielfahrzeug",
"statuslabels": {
"0": {
"title": "Undefiniert",
"color": "darkgray",
"private": false
},
"3": {
"title": "Betrieblich",
"color": "blue",
"private": false
},
"2": {
"title": "Privat, sichtbar",
"color": "yellow",
"private": false
},
"1": {
"title": "Privatfahrt",
"color": "red",
"private": true
},
"4": {
"title": "An-/Heimfahrt",
"color": "black",
"private": false
}
},
"alert": {
"id": "123456",
"address": "Stephansplatz 1, 1010 Wien, Österreich",
"private": "3",
"category": "",
"note": ""
}
}
},
"tracker": {
"title": "Beispielfahrzeug"
}
}
Response data
| Field(s) | Description |
|---|---|
| mode | The driver mode which is the same for all drivers of a user. It defines how a driver identifies himself in the system. It can either be "qr" (the driver scans a QR code on the vehicle) or "ibutton" (the driver uses an iButton in the vehicle after a trip has been started). |
| name | The name of the driver (equals the name field in "4.1. List drivers"). |
| categories |
List of time categories available which can be edited by a technical administrator.
Time categories are the same for all drivers of a user.
They are indexed by the system value (which can be either "drive", "standby", "work", "rest" or also randomly generated strings
for additional categories) and have the following parameters:
|
| category |
Holds the system values of the currently active time category incl. the optional subcategory and the current category duration.
If the time category "drive" is active, there is additional information available:
|
| tracker | The vehicle that the driver is currently connected with, meaning that the driver scanned the QR code of the respective car. Only relevant if "mode" is "qr". |
API endpoint: https://www.gps365.at/api_driver/account/status Request type: GET Authorization: driver [DRIVER_TOKEN, e.g. 1ad35ddc5934cff26c650c7e8d28a395]
A simplified endpoint which is similar to the one described at "5.1. Get account details" but only returns the active time category and the vehicle that the driver is currently connected with. In order to make sure that the user interface is up-to-date you might want to query this endpoint regularly as these fields might change on the server side (e.g. after a trip has ended, the category will change from "drive" to another category like "work" or "rest").
Request example
curl -X GET https://www.gps365.at/api_driver/account/status \
-H "Authorization: driver 1ad35ddc5934cff26c650c7e8d28a395"
Response example #1
(HTTP response code: 200 OK)
{
"category": {
"category": "drive",
"subcategory": "",
"duration": 360,
"tracker": {
"title": "Beispielfahrzeug",
"statuslabels": {
"0": {
"title": "Undefiniert",
"color": "darkgray",
"private": false
},
"3": {
"title": "Betrieblich",
"color": "blue",
"private": false
},
"2": {
"title": "Privat, sichtbar",
"color": "yellow",
"private": false
},
"1": {
"title": "Privatfahrt",
"color": "red",
"private": true
},
"4": {
"title": "An-/Heimfahrt",
"color": "black",
"private": false
}
},
"alert": {
"id": "123456",
"address": "Stephansplatz 1, 1010 Wien, Österreich",
"private": "0",
"category": "",
"note": ""
}
}
},
"tracker": {
"title": "Beispielfahrzeug"
}
}
Response example #2
(HTTP response code: 200 OK)
{
"category": {
"category": "work",
"subcategory": "3c16d5",
"duration": 360,
},
"tracker": {
"title": "Beispielfahrzeug"
}
}
Response data
Format of response data equals the one described at "5.1. Get account details" with the difference that only the fields category and tracker are returned.
API endpoint: https://www.gps365.at/api_driver/account/category Request type: PUT Authorization: driver [DRIVER_TOKEN, e.g. 1ad35ddc5934cff26c650c7e8d28a395]
This endpoint is used to set a new time category for the given driver. Note that you can only set a new time category if the category currently active is "selectable" (see "categories" at "5.1. Get account details") and the time category that you're about to set is "selectable" too.
Request parameters
| Parameter | Description |
|---|---|
|
category (required) |
The system value of the new time category. |
|
subcategory (optional) |
The system value of the new time subcategory. Note that if there are subcategories available for a category, the subcategory is required. |
Request example
curl -X PUT https://www.gps365.at/api_driver/account/category \
-H "Authorization: driver 1ad35ddc5934cff26c650c7e8d28a395" \
-H "Content-Type: application/json" \
-d '{ "category":"rest", "subcategory":"" }'
Response example #1 (success)
(HTTP response code: 200 OK)
{
"message": "Category `rest` has been set successfully.",
"category": {
"category": "rest",
"subcategory": "",
"duration": 360,
},
"tracker": {
"title": "Beispielfahrzeug"
}
}
Response example #2 (error, trying to unset an active category that is not "selectable")
(HTTP response code: 400 Bad Request)
{
"message": "Cannot unset current category."
}
Response example #3 (error, trying to set an active category that is not "selectable")
(HTTP response code: 400 Bad Request)
{
"message": "Invalid category or subcategory."
}
Response data
In case of a successful request, you get a confirmation message as well as the current category and tracker, just as if you had queried the account status endpoint. For further details see "5.2. Get account status".
API endpoint: https://www.gps365.at/api_driver/account/tracker Request type: PUT Authorization: driver [DRIVER_TOKEN, e.g. 1ad35ddc5934cff26c650c7e8d28a395]
If the driver is in QR-mode (see "mode" at "5.1. Get account details"), you can set a new tracker by sending the tracker token to this endpoint. The trackers' QR-codes hold their respective tracker tokens, thus by scanning a QR-code you will get the token required.
One driver can only have one tracker connected and one tracker can only be connected to one driver. Therefore when setting a new tracker, the tracker that has been connected to the driver before will automatically be unset. Also if another driver has been connected to the newly assigned tracker, that connection will be unset too.
Note that it is not possible to set a new tracker if there is another driver currently connected with this tracker who has "drive" set as category. This means that if driver A is currently driving, driver B has to wait until this trip has ended before he can be connected with this tracker.
Request parameters
| Parameter | Description |
|---|---|
|
tracker_token (required) |
The token of the tracker. (e.g. 57a41d6b0064128c) |
Request example
curl -X PUT https://www.gps365.at/api_driver/account/tracker \
-H "Authorization: driver 1ad35ddc5934cff26c650c7e8d28a395" \
-H "Content-Type: application/json" \
-d '{ "tracker_token":"57a41d6b0064128c" }'
Response example #1 (success)
(HTTP response code: 200 OK)
{
"message": "Tracker `57a41d6b0064128c` has been set successfully.",
"category": {
"category": "rest",
"subcategory": "",
"duration": 360,
},
"tracker": {
"title": "Beispielfahrzeug"
}
}
Response example #2 (error, trying to set a new tracker that is connected with a driver who is currently in "drive" category)
(HTTP response code: 400 Bad Request)
{
"message": "Cannot unset current driver while `drive` category is active."
}
Response data
In case of a successful request, you get a confirmation message as well as the current category and tracker, just as if you had queried the account status endpoint. For further details see "5.2. Get account status".
API endpoint: https://www.gps365.at/api_driver/account/tracker Request type: DELETE Authorization: driver [DRIVER_TOKEN, e.g. 1ad35ddc5934cff26c650c7e8d28a395]
Use this endpoint to unset the connection between the given driver and the connected tracker (if one exists). Note that it is not possible to unset the tracker if the driver is currently in "drive" category.
Request example
curl -X DELETE https://www.gps365.at/api_driver/account/tracker \
-H "Authorization: driver 1ad35ddc5934cff26c650c7e8d28a395"
Response example #1 (success)
(HTTP response code: 200 OK)
{
"message": "Tracker has been unset successfully.",
"category": {
"category": "rest",
"subcategory": "",
"duration": 360,
},
"tracker": {
"title": "Beispielfahrzeug"
}
}
Response example #2 (error, trying to unset the tracker while is in "drive" category)
(HTTP response code: 400 Bad Request)
{
"message": "Cannot unset tracker as driver has `drive` category active."
}
Response data
In case of a successful request, you get a confirmation message as well as the current category and tracker, just as if you had queried the account status endpoint. For further details see "5.2. Get account status".
API endpoint: https://www.gps365.at/api_driver/account/trip Request type: PUT Authorization: driver [DRIVER_TOKEN, e.g. 1ad35ddc5934cff26c650c7e8d28a395]
While the driver is in the "drive" time category, details of the trip can be modified. There are currently three settings available that correspond to fields in category.tracker.alert in the data seen in "5.1. Get account details":
Request example
curl -X PUT https://www.gps365.at/api_driver/account/trip \
-H "Authorization: driver 1ad35ddc5934cff26c650c7e8d28a395" \
-H "Content-Type: application/json" \
-d '{ "private":"3", "category":"Kundentermin", "note":"Kunde Fa. Beispiel-Bau" }'
Response example
{
"message": "Data has been saved successfully.",
"category": {
"category": "drive",
"subcategory": "",
"duration": 360,
"tracker": {
"title": "Beispielfahrzeug",
"statuslabels": {
"0": {
"title": "Undefiniert",
"color": "darkgray",
"private": false
},
"3": {
"title": "Betrieblich",
"color": "blue",
"private": false
},
"2": {
"title": "Privat, sichtbar",
"color": "yellow",
"private": false
},
"1": {
"title": "Privatfahrt",
"color": "red",
"private": true
},
"4": {
"title": "An-/Heimfahrt",
"color": "black",
"private": false
}
},
"alert": {
"id": "123456",
"address": "Stephansplatz 1, 1010 Wien, Österreich",
"private": "3",
"category": "Kundentermin",
"note": "Kunde Fa. Beispiel-Bau"
}
}
},
"tracker": {
"title": "Beispielfahrzeug"
}
}
Response data
In case of a successful request, you get a confirmation message as well as the current category and tracker, just as if you had queried the account status endpoint. The category.tracker.alert node holds the newly set values for private status, category and note of the trip. For further details see "5.2. Get account status".
API endpoint: https://www.gps365.at/api_driver/workdays/report/[DATE] Request type: GET Authorization: driver [DRIVER_TOKEN, e.g. 1ad35ddc5934cff26c650c7e8d28a395]
This endpoint delivers a full report for the requested date. The date has to be set in the URL (format: yyyy-mm-dd).
Request example
curl -X GET https://www.gps365.at/api_driver/workdays/report/2024-01-01 \
-H "Authorization: driver 1ad35ddc5934cff26c650c7e8d28a395"
Response example
{
"summary": {
"start": 32400,
"duration": 61200,
"trackers": {
"Beispielfahrzeug": {
"distance": 100000,
"duration": 3600
},
"LKW Nr. 123": {
"distance": 180000,
"duration": 7200
}
}
},
"data": [
{
"start": 32400,
"duration": 3600,
"category": "Lenkzeit",
"icon": "drive",
"tracker": "Beispielfahrzeug",
"start_odometer": 80000000,
"end_odometer": 80100000,
"distance": 100000
},
{
"start": 36000,
"duration": 1800,
"category": "Sonstige Arbeitszeit › Büroarbeit",
"icon": "work"
},
{
"start": 37800,
"duration": 1800,
"category": "Lenkzeit",
"icon": "drive",
"tracker": "LKW Nr. 123",
"start_odometer": 200000000,
"end_odometer": 200060000,
"distance": 60000
},
{
"start": 39600,
"duration": 3600,
"category": "Lenkpause (Arbeitsbereitschaft)",
"icon": "standby"
},
{
"start": 43200,
"duration": 3600,
"category": "Ruhezeit",
"icon": "rest"
},
{
"start": 46800,
"duration": 3600,
"category": "Sonstige Arbeitszeit › Büroarbeit",
"icon": "work"
},
{
"start": 50400,
"duration": 5400,
"category": "Lenkzeit",
"icon": "drive",
"tracker": "LKW Nr. 123",
"start_odometer": 200060000,
"end_odometer": 200180000,
"distance": 120000
},
{
"start": 55800,
"duration": 5400,
"category": "Sonstige Arbeitszeit › Sonstiges",
"icon": "work"
}
],
"comments": [
"Ein erster Testkommentar.",
"Kommentar Nr. 2"
]
}
Response data
| Field | Description |
|---|---|
| summary |
An object holding a basic summary of the working day requested:
|
| data |
All time entries of the working day in detail:
|
| comments | A list of comments added by the driver for the day requested (e.g. to correct errors because of faulty operation). |