Coordinates API documentation

1. Introduction

This document gives you all the information necessary to connect external services with our system and gather tracker coordinate data.

Our Coordinates API offers a set of callable methods that you can send requests to. All of these requests 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 a message.

Timezone for requests and responses is UTC.

2. Authentification

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.

3. Response codes

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 (OK) / status "success"
  code 401 (Unauthorized) / status "error"
  code 404 (Not found) / status "error"

In case of an error you will find further details in response.message.

4. Trackers

4.1. List trackers

  API endpoint: https://www.gps365.at/api/trackers/list

Returns a list of all trackers belonging to the given user.

Request parameters

Parameter Description
api_token
(required)
The API token belonging to your user account.
(e.g. 392ea8428d10b0392c399c93810045a9)

Request example

curl -X POST https://www.gps365.at/api/trackers/list \
     -d api_token="392ea8428d10b0392c399c93810045a9"

Response example

{
  "response": {
    "status": "success",
    "code": 200,
    "message": "OK"
  },
  "result": [
    {
      "id": 100,
      "title": "Tracker #1",
      "description": "First tracker",
      "group": "Tracker",
      "phone": "+43688123456789",
      "imei": "0133422688755999",
      "iccid": "0133422688755999",
      "serial_number": "10100"
    },
    {
      "id": 101,
      "title": "Tracker #2",
      "description": null,
      "group": "Tracker",
      "phone": "+43688123456780",
      "imei": "0133422688755990",
      "iccid": "0133422688755990",
      "serial_number": "10101"
    }
  ]
}

Response data

Field Description
id The unique ID of the tracker which is immutable.
title The title of the tracker which can be edited by the user.
description The description of the tracker which can be edited by the user. It is an optional field and thus can be null.
group The group of the tracker which can be edited by the user.
phone The phone number of the tracker which is set by a technical administrator.
imei The IMEI number of the tracker which is set by a technical administrator.
iccid The ICCID of the tracker which is set by a technical administrator.
serial_number The serial number of the tracker which is set by a technical administrator.

5. Coordinates

5.1. Get latest coordinates

  API endpoint: https://www.gps365.at/api/coordinates/live

Returns the most recent coordinate for every tracker belonging to the user (only one row per tracker). The returned data object is indexed by the tracker IDs.

While a tracker is moving, the shortest duration between two coordinates is around 5 seconds. Therefore if you query this endpoint every 10 seconds you will almost get live data. Nevertheless we recommend integrating some logic that reduces the number of requests if you get the same coordinate multiple times, e.g. while the vehicle is parking, and increase the interval as soon as new coordinates are coming in.

Request parameters

Parameter Description
api_token
(required)
The API token belonging to your user account.
(e.g. 392ea8428d10b0392c399c93810045a9)
trackers
(optional)
Array of tracker IDs in case you only want to query certain trackers.

Request example
(only requesting data for tracker IDs 100 and 101)

curl -X POST https://www.gps365.at/api/coordinates/live \
     -d api_token="392ea8428d10b0392c399c93810045a9" \
     -d trackers[]="100" \
     -d trackers[]="101"

Response example

{
  "response": {
    "status": "success",
    "code": "200",
    "message":"OK"
  },
  "result": {
    "100": {
      "tracker_id": 100, 
      "date": "2020-09-29 20:30:22",
      "latitude": 48.164235,
      "longitude": 16.189012,
      [...]
    },
    "101": {
      "tracker_id": 101,
      "date": "2020-09-29 20:25:52",
      "latitude": 47.975134,
      "longitude": 15.824156,
      [...]
    }
  }
}

Response data

Field(s) Description
tracker_id The ID of the tracker which the coordinate belongs to.
date The date when the coordinate was saved by the tracker, timezone is UTC.
latitude / longitude The latitude / longitude of the coordinate in Decimal Degrees format (WGS84).
speed The speed in kilometers per hour.
azimuth An integer value determining the direction from 0 (north) clockwise to 360 (north), thus 90 being east, 180 being south and 270 being west.
altitude A rough estimate of the tracker's altitude in meters above sea level.
gsmsignal The mobile network signal strength (*not available yet*).
powervoltage The battery voltage of the vehicle in millivolt. Availability depends on the hardware used.
analog1 - analog4 Float values of the tracker's analog inputs. Availability depends on the hardware used, interpretation of the value depends on tracker installation and configuration.
temperature1 - temperature4 Float values of the tracker's temperature inputs. In most cases the values are given in degrees Celsius. Availability depends on the hardware used, interpretation of the value depends on tracker installation and configuration.
motion A boolean value determining if the tracker is moving, based on the motion sensor of the hardware. Availability depends on the hardware used.
input1 - input8 Boolean values determining whether or not a digital input is active or inactive. Availability depends on the hardware used, interpretation of the value depends on tracker installation and configuration, except for input1 which is always ignition.
input1_duration - input8_duration Integer values that hold the duration (in seconds) of how long a digital input has been active, starting with the installation of the tracker. The value can be adjusted by the user through a calibration page.
output1 - output8 Boolean values determining whether or not a digital output is active or inactive. Availability depends on the hardware used, interpretation of the value depends on tracker installation and configuration.
output1_duration - output8_duration Integer values that hold the duration (in seconds) of how long a digital output has been active, starting with the installation of the tracker. The value can be adjusted by the user through a calibration page.
odometer An integer value that holds the mileage (in meters) of the vehicle, starting with the installation of the tracker. The value can be adjusted by the user through a calibration page.
mobile_country_id / mobile_network_id Information about the country and mobile network that the tracker is connected to (*not available yet*).
sendingdate The date when the coordinate was received by the server, timezone is UTC.

5.2. Get historic coordinates (tracker timestamp based)

  API endpoint: https://www.gps365.at/api/coordinates/list

Returns a list of coordinates for every tracker belonging to the user (multiple rows per tracker). By default this method returns up to 100 rows for every tracker, starting with the oldest record available (sorted ascending). However, if you're requesting data for only one specific tracker, the maximum number of returned rows is raised to 5,000 automatically to enable efficient bulk exports (see section "Bulk exports"). The returned data object is always indexed by the tracker IDs.

Default mode

In order to get the desired rows (e.g. everything within the last five minutes) you can specify a start and end date for every tracker individually. Using individual date ranges for every tracker is crucial as trackers can have short downtimes, most likely when they lose connection to the mobile network (e.g. in an underground garage). Therefore data transmission to the server can be delayed and every tracker should be queried with the date of the last row that was exported to your system.

To ensure reasonable performance, the maximum date range for each tracker is five weeks. If you supply a start and end date, the end date must not be more than five weeks past the start date. Otherwise the end date will automatically be set to a valid value. If you don't supply a start date, the default value is "2000-01-01 00:00:00". Considering the five weeks limit, the default end date will automatically be set to "2000-02-05 00:00:00".

Beside the actual result of the query, this method additionally delivers a summary block, also indexed by the tracker IDs, telling you the number of rows returned ("rows"), the number of total rows matching your query ("total") and the date of the last row ("last_date") which is the date that you will want to use for a subsequent request. Note that "last_date" is the date of the last record within the query result. As the start and end date are compared with "greater equal (>=)" / "lower equal (<=)", the subsequent request will actually deliver the same record again (the previously last record then being the first record in the subsequent request). In order to avoid this, you can increase the "last_date" by one second and use this value as the next start date.

In case that a tracker has a longer downtime (e.g. last sent data on "2020-03-20 12:00:00" and the next time on "2020-05-20 12:00:00") you won't be able to fetch the new data if you provide "2020-03-20 12:00:00" as start date as the end date will be set to "2020-04-24 12:00:00". Therefore, if you're querying data from the past, make sure to handle cases where you get empty results and automatically increase the start date for consecutive requests. This also applies if you send a request without setting a specific start date. Based on the default start and end date you will most likely get an empty result in this case too.

While a tracker is moving, the shortest duration between two coordinates is around 5 seconds. Therefore a moving vehicle creates up to 60 coordinates in 5 minutes. If you're planning to query data in a short interval, we recommend one request every 3-5 minutes. This will make sure that you don't exceed the limit of 100 rows per request while also having a good mix of being almost live without running too many requests.

Another approach would be to query all the rows once a day. In this case you will typically need multiple request, as a tracker usually creates more than 100 coordinates per day. By using the information in the summary block (especially the "total" value) you will easily be able to calculate the number of requests needed to get all rows of the last day. You may also want to specify an end date in this scenario to make sure that the number of total rows doesn't increase while you're sending your requests (e.g. because the vehicle is currently moving thus continuously creating additional data). A more efficient way for this task is to query data for each tracker sequentially as this will allow to get up to 5,000 rows per request. For details see the section "Bulk exports" below.

Bulk exports

Based on the fact that some users have hundreds of trackers, the number of rows returned per tracker is – by default – limited to only 100. To enable easier bulk exports for data of a specific tracker, this limit gets raised automatically if you send the "trackers" parameter with only one tracker ID and at least a start date. As soon as you send no tracker ID or more than one tracker ID, the limit will automatically be reduced to 100.

Request parameters

Parameter Description
api_token
(required)
The API token belonging to your user account.
(e.g. 392ea8428d10b0392c399c93810045a9)
trackers
(optional)
Array of start dates (or array with start and end dates) indexed by tracker IDs. Lets you limit your query to the given trackers within a certain time periods. Start date defaults to "2000-01-01 00:00:00", end date must not be more than five weeks after the start date, thus defaults to "2000-02-05 00:00:00".

Request example
(only requesting data for tracker IDs 100 (with start and end date) and 101 (with start date only))

curl -X POST https://www.gps365.at/api/coordinates/list \
     -d api_token="392ea8428d10b0392c399c93810045a9" \
     -d trackers[100][]="2020-01-01 08:00:00" \
     -d trackers[100][]="2020-01-01 12:00:00" \
     -d trackers[101]="2020-01-01 10:00:00"

Response example

{
  "response": {
    "status": "success",
    "code": "200",
    "message":"OK"
  },
  "result": {
    "100": [
      {
        "tracker_id": 100, 
        "date": "2020-01-01 08:00:13",
        "latitude": 48.164239,
        "longitude": 16.189014,
        [...]
      },
      {
        "tracker_id": 100, 
        "date": "2020-01-01 08:00:19",
        "latitude": 48.164235,
        "longitude": 16.189012,
        [...]
      },
      [...]
    ],
    "101": [
      {
        "tracker_id": 101,
        "date": "2020-01-01 10:01:02",
        "latitude": 47.975134,
        "longitude": 15.824156,
        [...]
      },
      [...]
    ]
  },
  "summary": {
    "100": {
      "start_date": "2020-01-01 08:00:00",
      "end_date": "2020-01-01 12:00:00",
      "rows": 100,
      "total": 350,
      "last_date": "2020-01-01 09:10:55"
    },
    "101": {
      "start_date": "2020-01-01 10:00:00",
      "end_date": "2020-09-29 20:30:52",
      "rows": 5,
      "total": 5,
      "last_date": "2020-09-29 20:30:28"
    }
  }
}

Response data

Format of response data equals the one described at "5.1. Get latest coordinates" with an additional summary block, indexed by tracker ID:

Field(s) Description
start_date Start of the time period of the query for the respective tracker. If a start date was sent with the request, this will equal the given start date, otherwise the default start date (2000-01-01 00:00:00) will be used.
end_date End of the time period of the query for the respective tracker. If an end date was sent with the request, this will equal the given end date, otherwise the current date / time will be used.
rows The number of rows returned for the respective tracker (max. 100 / 5,000 based on the type of query).
total The total number of rows available for the respective tracker and the given time period.
last_date Date of the last row returned for the respective tracker. This date can be used for subsequent requests if there are more total rows than rows returned in the response (total > rows).

5.3. Get historic coordinates (server timestamp based)

  API endpoint: https://www.gps365.at/api/coordinates/historic

Handling different timestamps for each tracker as described in "5.2. Get historic coordinates (tracker timestamp based)" sometimes can be difficult or even impossible, depending on the specific use case or implementation. Therefore we offer another approach for querying historic data which is based on the date / time when data was received by our servers.

This way it is possible to only supply one timestamp ("start_date") with the request, which determines when you last gathered data from our servers. The endpoint will then return all the data that was received after the given timestamp.

The limits for this endpoint are higher than the ones mentioned in "5.2. Get historic coordinates (tracker timestamp based)": If you query only one specific tracker, you will be able to fetch up to 10,000 rows in one request. Otherwise the number of rows per tracker will be limited to 500. The returned data object is also indexed by the tracker IDs and sorted by date ascending.

If there are more rows available than you can gather within one request, there is an optional "page" parameter which enables you to query the next pages. Keep in mind that when working with live data (e.g. when querying all data that came in within the last 10 minutes) you should definitely lock down the "end_date" in case you're querying pages 2, 3 etc. for multiple trackers.

The reason is simple: Imagine you have two trackers, A only having 5 rows, B having 150 rows. When you start your first query, you will receive 5 rows for A and 100 rows for B. A few seconds later you'll start a new request to get the rest of the data (i.e. the last 50 rows for B), so you add the parameter "page=2".

In the meantime, our servers received a new record for both trackers (A now having 6 rows, B having 151). When you query page 2 without supplying an "end_date", you will get 0 results for A (because the new 6th record is actually on page one, not on page two) and 51 results for B. So you'll most likely miss the new row for A.

Therefore it is crucial to use the "end_date" you received within the response for your first request when querying all other pages. This makes sure that the number of results stays the same over multiple requests. After you gathered all the pages, you can use this "end_date" as the "start_date" for the next request.

Another thing to keep in mind when working with live data: As there might be differences between the time on your server and our servers, we recommend making the first request (for page 1) without an "end_date" and then using the "end_date" from the first response for querying pages 2, 3 etc. Otherwise, if you add an "end_date" generated on your system, it is possible, that your "end_date" is in the "future" (at least according to our servers) and you run into the same issues with page 2, 3 etc. as described above.

To ensure reasonable performance, the maximum date range between start and end date is one week. If you don't supply a start date, the default value is "2000-01-01 00:00:00". Considering the limit of one week, the default end date will automatically be set to "2000-01-08 00:00:00". If you only send a start date and no (or an invalid) end date, the end date will automatically be set to a valid value.

Depending on your data collecting strategy, it might be more performant to query each tracker separately or all at once. If you send queries in a shorter interval, e.g. every 10 minutes, it is clearly recommended to query all trackers at once, especially as you should be able to gather all the data collected within 10 minutes with one request. On the other hand, if you query data only once a day, it might be better to query each tracker separately as this is typically faster than querying a lot of pages for all trackers.

Dates are compared using ">= start_date" and "< end_date". This way you can safely use the "end_date" that you received from the endpoint as the new "start_date" and will not receive rows twice as it is the case at "5.2. Get historic coordinates (tracker timestamp based)".

Request parameters

Parameter Description
api_token
(required)
The API token belonging to your user account.
(e.g. 392ea8428d10b0392c399c93810045a9)
trackers
(optional)
Array of tracker IDs in case you only want to query certain trackers.
start_date
(optional)
A start date for the query, defaults to "2000-01-01 00:00:00". The result will only contain data that was received at or after the given date / time.
end_date
(optional)
An end date for the query, must not be more than five weeks after the start date. Based on the default start date it defaults to "2000-02-05 00:00:00". The result will only contain data that was received before the given date / time. Mainly used in combination with the page parameter.
page
(optional)
The page number you want to query in case that there are more results than you can fetch within one request.

Request example #1
(requesting only data for tracker IDs 100 and 101)

curl -X POST https://www.gps365.at/api/coordinates/live \
     -d api_token="392ea8428d10b0392c399c93810045a9" \
     -d trackers[]="100" \
     -d trackers[]="101" \
     -d start_date="2020-01-01 00:00:00"

Response example

{
  "response": {
    "status": "success",
    "code": "200",
    "message":"OK"
  },
  "result": {
    "100": [
      {
        "tracker_id": 100, 
        "date": "2020-01-01 08:00:13",
        "latitude": 48.164239,
        "longitude": 16.189014,
        [...]
      },
      {
        "tracker_id": 100, 
        "date": "2020-01-01 08:00:19",
        "latitude": 48.164235,
        "longitude": 16.189012,
        [...]
      },
      [...]
    ],
    "101": [
      {
        "tracker_id": 101,
        "date": "2020-01-01 10:01:02",
        "latitude": 47.975134,
        "longitude": 15.824156,
        [...]
      },
      [...]
    ]
  },
  "summary": {
      "start_date": "2020-01-01 00:00:00",
      "end_date": "2020-01-01 12:30:00",
      "page": 1,
      "pages": 2,
      "trackers": {
          "100": {
              "rows": 5,
              "total": 5
          },
          "101": {
              "rows": 100,
              "total": 150
          }
      }
  }
}

Request example #2
(requesting page 2 based on request example #1 and response example above)

curl -X POST https://www.gps365.at/api/coordinates/live \
     -d api_token="392ea8428d10b0392c399c93810045a9" \
     -d trackers[]="100" \
     -d trackers[]="101" \
     -d start_date="2020-01-01 00:00:00" \
     -d end_date="2020-01-01 12:30:00" \
     -d page="2"

Response data

Format of response data equals the one described at "5.1. Get latest coordinates" with an additional summary block.

› API overview

Diese Website verwendet Cookies. Wenn Sie die Website weiter nutzen, gehen wir von Ihrem Einverständnis aus. Weitere Informationen zu unserem Umgang mit personenbezogenen Daten finden Sie in unserer Datenschutzerklärung.