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.

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).

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 400 (Bad Request) / status "error"
  code 401 (Unauthorized) / status "error"
  code 403 (Forbidden) / 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

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

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

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": "2024-04-19 16:01:50",
      "latitude": 48.164235,
      "longitude": 16.189012,
      [...]
    },
    "101": {
      "tracker_id": 101,
      "date": "2024-04-19 15:57:20",
      "latitude": 47.975134,
      "longitude": 15.824156,
      [...]
    }
  }
}

Response data

5.2. Get one historic coordinate

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

Returns the same data as the previous endpoint (i.e. one row per tracker, indexed by the tracker ID just as described in "5.1. Get latest coordinates"), but will fetch this coordinate for each tracker based on a certain date in the past.

Therefore, this endpoint requires you to define a date parameter in your request. The API is then looking for a coordinate which is nearest to the given date for each tracker. The coordinate returned can be from the exact same date that you defined, but more likely it will be from either before or after that (possibly even from a different date), depending on when the tracker has actually sent data.

This endpoint is particularly useful for example when you want to compare odometer values at different points in time in the past or when you want to illustrate a tracker's movement in a certain interval (e.g. every hour) without all the details in between.

Request parameters

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

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

Response example

{
  "response": {
    "status": "success",
    "code": "200",
    "message":"OK"
  },
  "result": {
    "100": {
      "tracker_id": 100, 
      "date": "2024-01-01 11:59:43",
      "latitude": 48.164235,
      "longitude": 16.189012,
      [...]
    },
    "101": {
      "tracker_id": 101,
      "date": "2024-01-01 12:02:07",
      "latitude": 47.975134,
      "longitude": 15.824156,
      [...]
    }
  }
}

Response data

Format of response data equals the one described at "5.1. Get latest coordinates".

5.3. Get multiple 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 "2024-03-20 12:00:00" and the next time on "2024-05-20 12:00:00") you won't be able to fetch the new data if you provide "2024-03-20 12:00:00" as start date as the end date will be set to "2024-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

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][]="2024-01-01 08:00:00" \
     -d trackers[100][]="2024-01-01 12:00:00" \
     -d trackers[101]="2024-01-01 10:00:00"

Response example

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

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:

5.4. Get multiple historic coordinates (server timestamp based)

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

Handling different timestamps for each tracker as described in "5.3. 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.3. 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.3. Get historic coordinates (tracker timestamp based)".

Request parameters

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

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

Response example

{
  "response": {
    "status": "success",
    "code": "200",
    "message":"OK"
  },
  "result": {
    "100": [
      {
        "tracker_id": 100, 
        "date": "2024-01-01 08:00:13",
        "latitude": 48.164239,
        "longitude": 16.189014,
        [...]
      },
      {
        "tracker_id": 100, 
        "date": "2024-01-01 08:00:19",
        "latitude": 48.164235,
        "longitude": 16.189012,
        [...]
      },
      [...]
    ],
    "101": [
      {
        "tracker_id": 101,
        "date": "2024-01-01 10:01:02",
        "latitude": 47.975134,
        "longitude": 15.824156,
        [...]
      },
      [...]
    ]
  },
  "summary": {
      "start_date": "2024-01-01 00:00:00",
      "end_date": "2024-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="2024-01-01 00:00:00" \
     -d end_date="2024-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