This document gives you all the technical information necessary to connect external services with our system and send or gather routing data.
Our Routing API offers an endpoint with a set of callable methods that you can send requests to.
API endpoint: https://www.gps365.at/api_routing/
All of these requests must have the params
and should be POST.
As response you will get a JSON encoded object. In case of a non-successful response, you will get an error code and detailled error information.
The timezone used is the local timezone of the authenticated user.
As mentioned before, all requests to the API must contain the parameter api_token. The API token is used to identify your user account.
Please log in to see your personal API token here.
Please make sure that your API token is handled with care. In case your token has been compromised, contact us immediately.
Note: As the API is optimised for performance, tracker 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 (trackers) (i.e. the user account which can grant permissions to other users).
Within the JSON encoded data object you will need to send a tracker ID and a date. While the date can be any valid date (format: yyyy-mm-dd), the tracker ID needs to be the specific ID of the device in our system.
If you don't have the possibility to save our tracker IDs in your system, you can either send the tracker title or the tracker description instead. You can set these values in our system according to your own needs. For example you can use the tracker description field to store the unique identifiers that you use in your system.
Below you can find a list of your trackers with their title and description:
Please log in to see a list of your trackers here.
Add one or multiple new locations to one or multiple tours. New locations will be added after all existing locations. In the response object you will get the IDs of the newly added locations. You can save the IDs to work with these locations later on.
| Argument | Value |
|---|---|
|
action (required) |
add_locations |
|
api_token (required) |
The API token belonging to your user account. (e.g. 392ea8428d10b0392c399c93810045a9) |
|
data (required) |
The locations you want to add (JSON encoded), details see below. Can either be a simple array if you want to add only one location or a numeric array containing multiple arrays with locations. |
Possible fields for data:
| Field | Description |
|---|---|
|
tracker_id (required) |
ID of the tracker you want to add the location to. If you cannot provide the tracker ID you can make use of the tracker_title or tracker_description fields instead. |
|
tracker_title (alternative to tracker_id) |
Used to identify the tracker if you cannot provide the tracker ID. |
|
tracker_description (alternative to tracker_id) |
Used to identify the tracker if you cannot provide the tracker ID. |
|
date (required) |
The tour date you want to add the location to. (format: yyyy-mm-dd) |
|
title (optional) |
The location title, between 2 and 100 characters. |
|
address (required) |
The address of the location which will be used for geocoding, between 2 and 100 characters. The address is required even if you provide GPS coordinates (latitude/longitude). |
|
latitude (optional) |
Latitude of the location as floating number. |
|
longitude (optional) |
Longitude of the location as floating number. |
|
description (optional) |
An additional description for the location, between 2 and 1,000 characters. |
|
priority (optional) |
Can be set to "1" to mark this location as important. Otherwise the field can be left empty. |
|
opening_hours_#_from opening_hours_#_to (optional) |
You can use these fields to define specific opening hours.
Up to three time frames are possible, just replace the "#" in the field name with either "1", "2" or "3". (format: hh:mm) |
|
stop_duration (optional) |
Define how long the stop at this location will take (in minutes, integer value). If the stop duration is left empty, the default stop duration of the tracker will be used. |
Detailed data example
(add three locations to today's tour of tracker ID 100)
[
{
"tracker_id": 100,
"date": "2024-05-05"
"title": "Schloss Mirabell",
"address": "Mirabellplatz, 5020 Salzburg",
"latitude": 47.805443,
"longitude": 13.041694,
"description": "www.salzburg.info",
"priority": "",
"opening_hours_1_from": "08:00",
"opening_hours_1_to": "18:00",
"stop_duration": "",
},
{
"tracker_id": 100,
"date": "2024-05-05"
"title": "Schloss Schönbrunn",
"address": "Schönbrunner Schlossstraße 47, 1130 Wien",
"latitude": 48.184909,
"longitude": 16.312283
"description": "www.schoenbrunn.at",
"priority": "1",
"opening_hours_1_from": "08:00",
"opening_hours_1_to": "18:30",
"stop_duration": 60,
},
{
"tracker_id": 100,
"date": "2024-05-05"
"title": "Schloss Ambras",
"address": "Schloßstraße 20, 6020 Innsbruck",
"latitude": 47.256570,
"longitude": 11.433630,
"description": "www.schlossambras-innsbruck.at",
"priority": "",
"opening_hours_1_from": "10:00",
"opening_hours_1_to": "17:00",
"stop_duration": "",
}
]
Request example (with basic data)
(add one location to today's tour of tracker ID 100)
curl -X POST https://www.gps365.at/api_routing/ \
-d action="add_locations" \
-d api_token="392ea8428d10b0392c399c93810045a9" \
-d data="[{\"tracker_id\":100,\"date\":\"2024-05-05\",\"address\":\"Mirabellplatz, 5020 Salzburg\"}]"
Response example (based on the request example above)
{
"response": {
"code": "200",
"status": "ok",
"message": "Added 1 location(s)"
},
"details": [
{
"status": "ok",
"id": 1
}
]
}
Retrieve one or multiple locations by their IDs. The fields returned are the same as documented in section 4.1., complemented by an additional field done, which is indicating whether or not the location has already been reached (either datetime value or null).
Locations that cannot be found (e.g. because they have been deleted), are not included in the result (no empty datasets). Locations are sorted in ascending order by tracker ID, date and tour order.
| Argument | Value |
|---|---|
|
action (required) |
get_locations |
|
api_token (required) |
The API token belonging to your user account. (e.g. 392ea8428d10b0392c399c93810045a9) |
|
data (required) |
The locations you want to retrieve (JSON encoded), details see below. |
Possible fields for data:
| Field | Description |
|---|---|
|
location_id (required) |
ID(s) of the location(s) you want to retrieve. Can either be an integer value if you want to retrieve only one location or a numeric array containing multiple location IDs. |
Detailed data example
(retrieve locations with ID 1, 2 and 3)
{
"location_id": [
1,
2,
3
]
}
Request example (with basic data)
(retrieve locations with ID 1)
curl -X POST https://www.gps365.at/api_routing/ \
-d action="get_locations" \
-d api_token="392ea8428d10b0392c399c93810045a9" \
-d data="{\"location_id\":[1]}"
Response example (based on the request example above)
{
"response": {
"code": "200",
"status": "ok",
"message": "Found 1 location(s)"
},
"details": [
{
"id": 1,
"tracker_id": 100,
"date": "2024-05-05",
"title": null,
"address": "Mirabellplatz, 5020 Salzburg",
"latitude": null,
"longitude": null,
"description": null,
"priority": null,
"opening_hours_1_from": null,
"opening_hours_1_to": null,
"opening_hours_2_from": null,
"opening_hours_2_to": null,
"opening_hours_3_from": null,
"opening_hours_3_to": null,
"stop_duration": null,
"done": null
}
]
}
Retrieve all locations of one or multiple tours. The fields returned are the same as documented in section 4.1., complemented by an additional field done, which is indicating whether or not the location has already been reached (either datetime value or null).
Locations are sorted in ascending order by tracker ID, date and tour order.
| Argument | Value |
|---|---|
|
action (required) |
get_tours |
|
api_token (required) |
The API token belonging to your user account. (e.g. 392ea8428d10b0392c399c93810045a9) |
|
data (required) |
The tours you want to retrieve (JSON encoded), details see below. Can either be a simple array if you want to retrieve only one tour or a numeric array containing multiple arrays with tours. |
Possible fields for data:
| Field | Description |
|---|---|
|
tracker_id (required) |
ID of the tracker you want to retrieve data for. If you cannot provide the tracker ID you can make use of the tracker_title or tracker_description fields instead. |
|
tracker_title (alternative to tracker_id) |
Used to identify the tracker if you cannot provide the tracker ID. |
|
tracker_description (alternative to tracker_id) |
Used to identify the tracker if you cannot provide the tracker ID. |
|
date (required) |
The tour date you want to retrieve. (format: yyyy-mm-dd) |
Detailed data example
(retrieve today's tour for tracker ID 100 and 101)
[
{
"tracker_id": 100,
"date": "2024-05-05"
},
{
"tracker_id": 101,
"date": "2024-05-05"
}
]
Request example (with basic data)
(retrieve today's tour for tracker ID 100)
curl -X POST https://www.gps365.at/api_routing/ \
-d action="get_tours" \
-d api_token="392ea8428d10b0392c399c93810045a9" \
-d data="[{\"tracker_id\":100,\"date\":\"2024-05-05\"}]"
Response example (based on the request example above)
{
"response": {
"code": "200",
"status": "ok",
"message": "Found 1 location(s)"
},
"details": [
{
"id": 1,
"tracker_id": 100,
"date": "2024-05-05",
"title": null,
"address": "Mirabellplatz, 5020 Salzburg",
"latitude": null,
"longitude": null,
"description": null,
"priority": null,
"opening_hours_1_from": null,
"opening_hours_1_to": null,
"opening_hours_2_from": null,
"opening_hours_2_to": null,
"opening_hours_3_from": null,
"opening_hours_3_to": null,
"stop_duration": null,
"done": null
}
]
}
Delete all locations of one or multiple tours.
| Argument | Value |
|---|---|
|
action (required) |
reset_tours |
|
api_token (required) |
The API token belonging to your user account. (e.g. 392ea8428d10b0392c399c93810045a9) |
|
data (required) |
The tours you want to reset (JSON encoded), details see below. Can either be a simple array if you want to reset only one tour or a numeric array containing multiple arrays with tours. |
Possible fields for data:
| Field | Description |
|---|---|
|
tracker_id (required) |
ID of the tracker you want to reset. If you cannot provide the tracker ID you can make use of the tracker_title or tracker_description fields instead. |
|
tracker_title (alternative to tracker_id) |
Used to identify the tracker if you cannot provide the tracker ID. |
|
tracker_description (alternative to tracker_id) |
Used to identify the tracker if you cannot provide the tracker ID. |
|
date (required) |
The tour date you want to reset. (format: yyyy-mm-dd) |
Detailed data example
(reset today's tour for tracker ID 100 and 101)
[
{
"tracker_id": 100,
"date": "2024-05-05"
},
{
"tracker_id": 101,
"date": "2024-05-05"
}
]
Request example (with basic data)
(reset today's tour for tracker ID 100)
curl -X POST https://www.gps365.at/api_routing/ \
-d action="reset_tours" \
-d api_token="392ea8428d10b0392c399c93810045a9" \
-d data="[{\"tracker_id\":100,\"date\":\"2024-05-05\"}]"
Response example (based on the request example above)
{
"response": {
"code": "200",
"status": "ok",
"message": "Reset 1 tour(s) with 1 location(s)"
},
"details": [
{
"status": "ok"
}
]
}
Send one or multiple tours to the navigation system in the vehicle(s).
| Argument | Value |
|---|---|
|
action (required) |
send_tours |
|
api_token (required) |
The API token belonging to your user account. (e.g. 392ea8428d10b0392c399c93810045a9) |
|
data (required) |
The tours you want to send (JSON encoded), details see below. Can either be a simple array if you want to send only one tour or a numeric array containing multiple arrays with tours. |
Possible fields for data:
| Field | Description |
|---|---|
|
tracker_id (required) |
ID of the tracker to which you want to send the tour to. If you cannot provide the tracker ID you can make use of the tracker_title or tracker_description fields instead. |
|
tracker_title (alternative to tracker_id) |
Used to identify the tracker if you cannot provide the tracker ID. |
|
tracker_description (alternative to tracker_id) |
Used to identify the tracker if you cannot provide the tracker ID. |
|
date (required) |
The date of the tour you want to send. (format: yyyy-mm-dd) |
Detailed data example
(send today's tour for tracker ID 100 and 101)
[
{
"tracker_id": 100,
"date": "2024-05-05"
},
{
"tracker_id": 101,
"date": "2024-05-05"
}
]
Request example (with basic data)
(send today's tour for tracker ID 100)
curl -X POST https://www.gps365.at/api_routing/ \
-d action="send_tours" \
-d api_token="392ea8428d10b0392c399c93810045a9" \
-d data="[{\"tracker_id\":100,\"date\":\"2024-05-05\"}]"
Response example (based on the request example above)
{
"response": {
"code": "200",
"status": "ok",
"message": "Sent 1 tour(s)"
},
"details": [
{
"status": "ok"
}
]
}
In the JSON encoded response object you will find the fields response.code and response.status. The possible values for these fields are:
code 200 / status "ok" or "error" code 400 / status "bad request" code 401 / status "unauthorized"
Note that for successful requests you can either get status "ok" or "error". Status "ok" means that every row in you data object was processed successfully. In case of errors with one or multiple lines you will get status "error" and can find more information in the details object.