Track¶

This section includes API calls that allow you to interact with tracks and retrieve track points.

Learn more about the track API by following our instructions.

API actions¶

API path: /track.

download¶

This method allows you to download track points as a KML/KMZ file which can be used in other apps to show tracks.

Parameters¶

Example¶

Let's consider an example, where we're looking for a KML file for a tracker with ID 1683258 that doesn't break down by stops. The data should cover trips starting from 3:24 AM to 6:24 AM on November 19, 2023, according to the user's local time.

curl -X POST 'https://api.navixy.com/v2/track/download' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 1683258, "from": "2023-11-19 03:24:00", "to": "2023-11-19 06:24:00", "format": "kml", "split": false}'

Response¶

In case the available storage period is not exceeded, you will get the file.

!!!+ example "KML file example with two points"

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:xal="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">
  <Document>
    <name>track-John (Scania) 2023-11-19 03:24:00</name>
    <Placemark>
      <name>point #1</name>
      <visibility>1</visibility>
      <description>2023-11-19 03:24:03</description>
      <TimeStamp>
        <when>2023-11-19T03:24:03.000-06:00</when>
      </TimeStamp>
      <ExtendedData>
        <Data name="speed">
          <value>37</value>
        </Data>
        <Data name="heading">
          <value>27</value>
        </Data>
      </ExtendedData>
      <Point>
        <coordinates>-78.768105,43.1172216</coordinates>
      </Point>
    </Placemark>
    <Placemark>
      <name>point #2</name>
      <visibility>1</visibility>
      <description>2023-11-19 03:27:11</description>
      <TimeStamp>
        <when>2023-11-19T03:27:11.000-06:00</when>
      </TimeStamp>
      <ExtendedData>
        <Data name="speed">
          <value>57</value>
        </Data>
        <Data name="heading">
          <value>13</value>
        </Data>
      </ExtendedData>
      <Point>
        <coordinates>-78.7549233,43.1356483</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>
```

For example, if the device's plan has maximum available storage period 3 months (default value) and we request data from 6 months, the response will contain JSON with the next information:

{
  "list": [],
  "limit_exceeded": true,
  "success": true
}

Errors¶

• 201 - Not found in database – the tracker ID in your request may not match any trackers linked to the user account with this session hash. Ensure the correct tracker_id and hash of an appropriate user are used.
• 208 - Device blocked – if a tracker exists under this user account but is currently inactive due to tariff plan restrictions or any other reason.
• 211 - Requested time span is too big – If the interval between the "from" and "to" dates is too large, it may exceed the maximum value defined in the API configuration.

list¶

This method retrieves a list of tracks for a given tracker within a specified time period.

Parameters¶

Example¶

For example, if we need to retrieve all trips for tracker 1683258 in November, without applying smart filter, including LBS points recorded, without clustering, separated by parkings, while also counting the number of events that occur during each trip, we only need to specify the "filter" and "count_events" from optional parameters. This is because the other optional settings will provide us with necessary info by default.

curl -X POST 'https://api.navixy.com/v2/track/list' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 1683258, "from": "2023-11-01 03:24:00", "to": "2023-11-30 06:24:00", "filter": false, "count_events": true}'

Response¶

{
  "success": true,
  "limit_exceeded": false,
  "list": [track_info]
}

• limit_exceeded - boolean. It will be true if the requested time period surpasses the limit set in the tracker's tariff. For instance, if the device's plan has a maximum storage period of three months (the default value), and we request trips for six months.
• list - an array of JSON objects containing track information. It consists of zero or more JSON objects. Zero objects indicates that there were no trips based on the track options or the device didn't supply any points to the platform.

where track_info is either regular, single_report, merged or cluster:

regular object:

{
  "id": 123456,
  "start_date": "2023-11-23 03:39:44",
  "start_address": "1255 6th Ave, New York, NY 10020, USA",
  "max_speed": 62,
  "end_date": "2023-11-23 06:39:44",
  "end_address": "888 5th Ave, New York, NY 10021, USA",
  "length": 5.5,
  "points": 327,
  "avg_speed": 49,
  "event_count": 3,
  "norm_fuel_consumed": 1.07,
  "type": "regular",
  "gsm_lbs": false,
  "points_list": [point_info],
  "bounds": {
    "nw": {
      "lat": 57.151005,
      "lng": 59.92729333
    },
    "se": {
      "lat": 56.47945333,
      "lng": 61.19021833
    }
  }
}

• id - int. Track id.
• start_date - date/time. Track start date, in user's timezone.
• start_address - string. Track start address.
• max_speed - int. Maximum speed registered during track in km/h.
• end_date - date/time. Track end date, in user's timezone.
• end_address - string. Track end address.
• length - float. Track length in kilometers.
• points - int. Total number of points in a track.
• avg_speed - int. Average speed in km/h.
• event_count - int. Number of events recorded during this track. This field will not be present if "count_events" is set to false.
• norm_fuel_consumed - float. Amount of fuel consumed during the track, measured in litres. This field will not be present if there's no vehicle_object linked to the tracker or if "normAvgFuelConsumption" is not defined for the linked vehicle object.
• type - enum: regular, single_report, merged, cluster. Track type.
• gsm_lbs - optional boolean. GSM LBS point flag.
• points_list - array of JSON objects. A list of point info.
• bounds - object. North-west and south-east coordinates of the bounding box that contains all points.

single_report object is returned when the device operates in "interval" mode or only one point per track is provided (for example, an M7 tracker operating in interval mode):

{
  "id": 123456,
  "start_date": "2023-11-24 03:39:44",
  "start_address": "1255 6th Ave, New York, NY 10020, USA",
  "avg_speed": 34,
  "gsm_lbs": false,
  "type": "single_report",
  "precision": 10,
  "points_list": [point_info]
}

• id - int. Track id.
• start_date - date/time. Date when the tracker registered the point, in user's timezone.
• start_address - string. Point address.
• avg_speed - int. Average speed in km/h.
• gsm_lbs - optional boolean. GSM LBS point flag.
• type - enum: regular, single_report, merged, cluster. Track type.
• precision - optional int. Precision of the location in meters. Its presence relies on the device model.
• points_list - array of JSON objects. A list of point info.

merged object. Only returned if "split" is set to false:

{
  "start_date": "2023-11-24 03:39:44",
  "start_address": "1255 6th Ave, New York, NY 10020, USA",
  "max_speed": 62,
  "end_date": "2023-11-24 06:39:44",
  "end_address": "888 5th Ave, New York, NY 10021, USA",
  "length": 5.5,
  "points": 327,
  "avg_speed": 49,
  "event_count": 3,
  "norm_fuel_consumed": 1.07,
  "type": "merged",
  "gsm_lbs": false,
  "points_list": [point_info],
  "bounds": {
    "nw": {
      "lat": 57.151005,
      "lng": 59.92729333
    },
    "se": {
      "lat": 56.47945333,
      "lng": 61.19021833
    }
  }
}

• start_date - date/time. Track start date, in user's timezone. It signifies the initial point identified as a track for a specified time period.
• start_address - string. Track start address.
• max_speed - int. Maximum speed registered during period in km/h.
• end_date - date/time. Track end date, in user's timezone. It signifies the last point identified as a track for a specified time period.
• end_address - string. Track end address.
• length - float. Track length in kilometers.
• points - int. Total number of points in a track.
• avg_speed - int. Average speed in km/h.
• event_count - int. Number of events recorded during period. This field will not be present if "count_events" is set to false.
• norm_fuel_consumed - float. Amount of fuel consumed during period, measured in litres. This field will not be present if there's no vehicle_object linked to the tracker or if "normAvgFuelConsumption" is not defined for the linked vehicle object.
• type - enum: regular, single_report, merged, cluster. Track type.
• gsm_lbs - optional boolean. GSM LBS point flag.
• points_list - array of JSON objects. A list of point info.
• bounds - object. North-west and south-east coordinates of the bounding box that contains all points.

cluster object. Can be returned only if "split" is set to true:

{
  "start_date": "2023-11-24 03:39:44",
  "start_address": "1255 6th Ave, New York, NY 10020, USA",
  "end_date": "2020-09-24 06:39:44",
  "precision": 500,
  "points": [
    {
      "lat": 34.178868,
      "lng": -118.599672
    },
    {
      "lat": 31.738386,
      "lng": -106.453854
    }
  ],
  "bounds": {
    "nw": {
      "lat": 57.151005,
      "lng": 59.92729333
    },
    "se": {
      "lat": 56.47945333,
      "lng": 61.19021833
    }
  },
  "type": "cluster",
  "gsm_lbs": false
}

• start_date - date/time. Track start date, in user's timezone.
• start_address - string. Track start address.
• end_date - date/time. Track end date, in user's timezone.
• precision - optional int. Precision of the location in meters. Its presence relies on the device model.
• points - array of point objects in a cluster.
• type - enum: regular, single_report, merged, cluster. Track type.
• gsm_lbs - optional boolean. GSM LBS flag. true if a cluster contains only GSM LBS points.
• bounds - object. North-west and south-east coordinates of the bounding box that contains all points.

Errors¶

• 201 - Not found in database – the tracker ID in your request may not match any trackers linked to the user account with this session hash. Ensure the correct tracker_id and hash of an appropriate user are used.
• 208 - Device blocked – if a tracker exists under this user account but is currently inactive due to tariff plan restrictions or any other reason.
• 211 - Requested time span is too big – If the interval between the "from" and "to" dates is too large, it may exceed the maximum value defined in the API configuration.

read¶

This method fetches all track points that a GPS tracker has recorded and sent to the platform within a specified time frame. The timestamp for each point corresponds to when the tracker recorded the point, adjusted to the user's time zone.

Parameters¶

Example¶

For instance, if we need to obtain track points for tracker 1683258 that fall within November 1, and are solely part of track ID 923150, without applying a smart filter, LBS points and simplifier. Since these optional parameters by default are true, we should list them in our request.

curl -X POST 'https://api.navixy.com/v2/track/read' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 1683258, "track_id": 923150, "from": "2023-11-01 00:00:00", "to": "2023-11-01 23:59:59", "filter": false, "simplify": false, "include_gsm_lbs": false}'

Response¶

{
  "success": true,
  "limit_exceeded": true,
  "list": [point_info]
}

• limit_exceeded - boolean. It will be true if the requested time period surpasses the limit set in the tracker's tariff. For instance, if the device's plan has a maximum storage period of three months (the default value), and we request trips for six months.
• list - array of JSON objects. A list of point info.

point info¶

{
  "lat": 43.0375133,
  "lng": -79.226505,
  "alt": 0,
  "satellites": 10,
  "mileage": 43.93,
  "get_time": "2023-11-01 04:38:39",
  "address": "Kottmeier Road, Thorold, Golden Horseshoe, Ontario, Canada, L3B 5N6",
  "heading": 280,
  "speed": 53,
  "precision": 100,
  "gsm_lbs": false,
  "parking": false,
  "buffered": true
}

• lat - float. Represents latitude.
• lng - float. Represents longitude.
• alt - int. Indicates the altitude in meters.
• satellites - int. Shows the number of GPS satellites used to determine this point.
• mileage - float. Represents mileage.
• get_time - date/time. This is the GPS timestamp of the point, adjusted to the user's timezone.
• address - string. Represents the location's address. Will be "" if no address recorded. If no address has been recorded, it will appear as "". An address is recorded when it marks the beginning or end of a trip, or when an event occurs.
• heading - int. A value that represents the direction in degrees, with a range of 0 to 360. 0 corresponds to North.
• speed - int. A value representing speed in kilometers per hour.
• precision - optional int. A value indicating precision in meters. Its presence relies on the device model.
• gsm_lbs - optional boolean. It returns true if the location was detected by GSM LBS.
• parking - optional boolean. It will return true if the point does not correspond to a trip. Parking detection feature on the platform influences the categorization of points as either trip or parking states.
• buffered - optional boolean. It will return true if the point was initially saved in the device's memory and then sent to the server later. This parameter may vary based on the tracker model.

Errors¶

• 201 - Not found in database – the tracker ID in your request may not match any trackers linked to the user account with this session hash. Ensure the correct tracker_id and hash of an appropriate user are used.
• 208 - Device blocked – if a tracker exists under this user account but is currently inactive due to tariff plan restrictions or any other reason.
• 211 - Requested time span is too big – If the interval between the "from" and "to" dates is too large, it may exceed the maximum value defined in the API configuration.

visit/list¶

This method fetches IDs of zones and places that contain at least one track point.

Parameters¶

Example¶

For instance, if we need to obtain IDs of zones and places that contain at least one track point related to tracker 1683258 in January.

curl -X POST 'https://api.navixy.com/v2/track/visit/list' \
    -H 'Content-Type: application/json' \
    -d '{"hash": "22eac1c27af4be7b9d04da2ce1af111b", "tracker_id": 1683258, "from": "2024-01-01 00:00:00", "to": "2024-01-31 00:00:00"}'

Response¶

{
  "success": true,
  "value": {
    "zones": [
      54865,
      35284
    ],
    "places": [
      18404
    ]
  }
}

• zones - int array. List of zones IDs.
• places - int array. List of places IDs.

Errors¶

• 204 - Entity not found – the tracker ID in your request may not match any trackers linked to the user account with this session hash. Ensure the correct tracker_id and hash of an appropriate user are used.