> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/tracking/track.md). # Track A tracker's movement over a period, as trips with totals, as raw points, or as a KML file. A track is what a tracker did over a period: where it went, how far, and how fast. These operations return that movement as trips with totals, as the raw points behind them, or as a KML file for a mapping tool. What comes back from `track/list` depends on three switches. `split` decides whether the period is broken into separate trips or returned as one `merged` track. `cluster_single_reports` groups one-point trips by coordinate into `cluster` tracks. `filter` drops tracks judged too short by length and point count. The `type` on each track tells you which of those produced it. These operations take tracker IDs directly. To get the same data for an asset, whose device can change over the period, use [asset tracks](/docs/navixy-api/user-api/resources/tracking/asset.md) instead. For a worked example, see [how to get track points](/docs/navixy-api/user-api/guides/data-retrieval/get-track-points.md). ## Track object The object returned in `track/list`'s `list`. Which fields are present depends on `type`. ## The Track object ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"Track":{"type":"object","description":"One track: a period of movement reconstructed from the points a device sent. The same object serves tracker tracks and asset tracks. **`type` selects which fields are present**, and the four kinds are not interchangeable.\n\n`regular` is an ordinary trip. `single_report` appears when the device reports in interval mode or only one point exists, and has no end or length. `merged` is every track in the period combined, returned only when `split` was `false`. `cluster` is a group of single-point trips gathered by coordinate, returned only when `cluster_single_reports` was `true`.","properties":{"id":{"type":"integer","description":"Track ID. Present on `regular` and `single_report`, absent on `merged` and `cluster`."},"type":{"type":"string","description":"Which kind of track this is.","enum":["regular","single_report","merged","cluster"]},"start_date":{"type":"string","description":"Track start, in the user's time zone. On `single_report` it is when the point was registered."},"start_address":{"type":"string","description":"Address at the start."},"end_date":{"type":"string","description":"Track end, in the user's time zone. Absent on `single_report`."},"end_address":{"type":"string","description":"Address at the end. Absent on `single_report` and `cluster`."},"length":{"type":"number","description":"Track length in kilometres. Absent on `single_report` and `cluster`."},"points":{"description":"**One field name, two meanings, decided by `type`.** On `regular` and `merged` it is an integer, the total number of points in the track. On `cluster` it is a plain list of coordinates, the points gathered into the cluster, which is not the same thing as `points_list`. Absent on `single_report`.","oneOf":[{"type":"integer","description":"Total number of points in the track. `regular` and `merged`."},{"type":"array","description":"The coordinates gathered into this cluster. `cluster` only.","items":{"type":"object","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}]},"max_speed":{"type":"integer","description":"Highest speed recorded, in km/h. Absent on `single_report` and `cluster`."},"avg_speed":{"type":"integer","description":"Average speed in km/h. Absent on `cluster`."},"event_count":{"type":"integer","description":"Events recorded during the track. **Absent unless `count_events` was `true`.**"},"norm_fuel_consumed":{"type":"number","description":"Fuel consumed during the track, in litres. **Absent when no vehicle is linked to the tracker, or the vehicle has no `norm_avg_fuel_consumption`.**"},"precision":{"type":"integer","description":"Accuracy of the location in metres. Present on `single_report` and `cluster`, and depends on the device model."},"gsm_lbs":{"type":"boolean","description":"Optional. GSM LBS flag. On a `cluster` it is `true` only when every point in it is GSM LBS."},"points_list":{"type":"array","description":"The track points. **Returned only when `with_points` was `true`.**","items":{"$ref":"#/components/schemas/TrackPoint"}},"bounds":{"type":"object","description":"North-west and south-east corners of the axis-aligned minimum bounding box.","properties":{"nw":{"type":"object","description":"North-west corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"se":{"type":"object","description":"South-east corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}}}},"TrackPoint":{"type":"object","description":"One point recorded by a tracker, timestamped when the tracker recorded it and shown in the user's time zone.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"alt":{"type":"integer","description":"Altitude in metres."},"satellites":{"type":"integer","description":"How many GPS satellites fixed this point."},"mileage":{"type":"number","description":"Mileage."},"get_time":{"type":"string","description":"GPS timestamp of the point, in the user's time zone."},"address":{"type":"string","description":"Address at the point, or an empty string when none was recorded. **An address is recorded only at the start or end of a trip, or where an event happened.**"},"heading":{"type":"integer","description":"Direction in degrees, 0 to 360, where 0 is North.","minimum":0,"maximum":360},"speed":{"type":"integer","description":"Speed in km/h."},"precision":{"type":"integer","description":"Optional. Accuracy in metres. Depends on the device model."},"gsm_lbs":{"type":"boolean","description":"Optional. `true` when the location came from GSM LBS rather than GPS."},"parking":{"type":"boolean","description":"Optional. `true` when the point is not part of a trip. Which points count as parking depends on the platform's parking detection settings."},"buffered":{"type":"boolean","description":"Optional. `true` when the point was held in the device's memory and sent later. Varies by tracker model."}}}}}} ``` `norm_fuel_consumed` is present only when a [vehicle object](/docs/navixy-api/user-api/resources/fleet/vehicle.md#vehicle-object) is linked to the tracker and has `normAvgFuelConsumption` defined. ## Track totals object ## The TrackTotals object ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"TrackTotals":{"type":"object","description":"Totals across every track returned.","properties":{"count":{"type":"integer","description":"Number of tracks."},"length":{"type":"number","description":"Sum of all track lengths, in kilometres."},"trip_duration":{"type":"string","description":"Total time spent moving, as an ISO 8601 duration."},"parking_duration":{"type":"string","description":"Total time spent stationary, as an ISO 8601 duration. Measured across the whole requested period, so it includes the gaps before the first track and after the last."},"norm_fuel_consumed":{"type":"number","description":"Fuel consumed across all tracks, in litres. Omitted entirely when no track carries a figure."}}}}}} ``` ## Point object The point object returned by `track/read`, and by `track/list` in each track's `points_list`. ## The TrackPoint object ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"components":{"schemas":{"TrackPoint":{"type":"object","description":"One point recorded by a tracker, timestamped when the tracker recorded it and shown in the user's time zone.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"alt":{"type":"integer","description":"Altitude in metres."},"satellites":{"type":"integer","description":"How many GPS satellites fixed this point."},"mileage":{"type":"number","description":"Mileage."},"get_time":{"type":"string","description":"GPS timestamp of the point, in the user's time zone."},"address":{"type":"string","description":"Address at the point, or an empty string when none was recorded. **An address is recorded only at the start or end of a trip, or where an event happened.**"},"heading":{"type":"integer","description":"Direction in degrees, 0 to 360, where 0 is North.","minimum":0,"maximum":360},"speed":{"type":"integer","description":"Speed in km/h."},"precision":{"type":"integer","description":"Optional. Accuracy in metres. Depends on the device model."},"gsm_lbs":{"type":"boolean","description":"Optional. `true` when the location came from GSM LBS rather than GPS."},"parking":{"type":"boolean","description":"Optional. `true` when the point is not part of a trip. Which points count as parking depends on the platform's parking detection settings."},"buffered":{"type":"boolean","description":"Optional. `true` when the point was held in the device's memory and sent later. Varies by tracker model."}}}}}} ``` Whether a point counts as trip or as parking is decided by the Navixy platform's [parking detection](https://www.navixy.com/docs/user/web-interface-docs/devices-doc/parking-detection/) settings. ## API actions API base path: `/track`. *** The file carries speed and heading as extended data on each placemark: ```xml track-John (Scania) 2023-11-19 03:24:00 point #1 1 2023-11-19 03:24:03 2023-11-19T03:24:03.000-06:00 37 27 -78.768105,43.1172216 ``` A request reaching further back than the device's plan retains, six months of data on a plan that stores three, returns JSON instead of a file: ```json { "list": [], "limit_exceeded": true, "success": true } ``` ## Download track as KML > Return the tracker's points over a period as a KML or KMZ file, for opening in another mapping application.\ > \ > \*\*The response is the file itself\*\*, not a JSON envelope. The one exception is when the tracker's plan does not reach back far enough to cover any of the requested period, in which case a JSON body comes back with \`limit\_exceeded\` set and an empty \`list\`. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tracks","description":"The trips a tracker made, the points behind them, the geofences and places they passed through, and waybills built from them. All resources under the /track/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/track/download":{"post":{"tags":["Tracks"],"summary":"Download track as KML","description":"Return the tracker's points over a period as a KML or KMZ file, for opening in another mapping application.\n\n**The response is the file itself**, not a JSON envelope. The one exception is when the tracker's plan does not reach back far enough to cover any of the requested period, in which case a JSON body comes back with `limit_exceeded` set and an empty `list`.","operationId":"trackDownload","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.","minimum":1},"from":{"type":"string","description":"Start of the period, in `YYYY-MM-DD HH:MM:SS` format, in the account's timezone."},"to":{"type":"string","description":"End of the period, in `YYYY-MM-DD HH:MM:SS` format. Must be after `from`."},"track_ids":{"type":"array","description":"Optional. Include only these tracks. Omit to include every valid point in the period. No duplicates.","items":{"type":"integer"}},"include_gsm_lbs":{"type":"boolean","description":"Optional. Default `true`. When `false` **and no `track_ids` are given**, GSM LBS points are excluded."},"simplify":{"type":"boolean","description":"Optional. Default `true`. Reduce the number of points in the file."},"point_limit":{"type":"integer","description":"Optional. Reduce the result to about this many points. Not a hard limit: the result can hold slightly more. Omit to use the platform's own simplification settings.","minimum":2,"maximum":3000},"filter":{"type":"boolean","description":"Optional. Default `true`. Filter the points, which currently affects LBS tracks only."},"format":{"type":"string","description":"Optional. Default `kml`. File format.","enum":["kml","kmz"]},"split":{"type":"boolean","description":"Optional. Default `false`. When `true`, the file groups tracks into folders split by stops, each with start and end markers."}},"required":["tracker_id","from","to"]}}}},"responses":{"200":{"description":"The track as a KML or KMZ file","content":{"application/vnd.google-earth.kml+xml":{"schema":{"type":"string","description":"The KML document."}},"application/vnd.google-earth.kmz":{"schema":{"type":"string","description":"The KMZ archive.","format":"binary"}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended. Error 211: the period between `from` and `to` exceeds the maximum the platform allows. Unlike the same code on `track/visit/list`, this one carries no `max_time_span`.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes): * 201 - Not found in the database. The tracker ID may match no tracker on the account the session hash belongs to. Check that the `tracker_id` and the hash belong to the same user. * 208 - Device blocked, when the tracker exists on the account but is inactive, whether through tariff restrictions or for another reason. * 211 - Requested time span is too big, when the interval between `from` and `to` exceeds the maximum the API configuration allows. *** ## List tracks > Return the tracker's tracks over a period, with totals across all of them.\ > \ > What comes back depends on three switches. \`split\` decides whether the period is broken into separate trips or returned as one \`merged\` track. \`cluster\_single\_reports\` groups one-point trips by coordinate into \`cluster\` tracks. \`filter\` drops tracks judged too short by length and point count.\ > \ > Points are left out unless \`with\_points\` is set. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tracks","description":"The trips a tracker made, the points behind them, the geofences and places they passed through, and waybills built from them. All resources under the /track/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"Track":{"type":"object","description":"One track: a period of movement reconstructed from the points a device sent. The same object serves tracker tracks and asset tracks. **`type` selects which fields are present**, and the four kinds are not interchangeable.\n\n`regular` is an ordinary trip. `single_report` appears when the device reports in interval mode or only one point exists, and has no end or length. `merged` is every track in the period combined, returned only when `split` was `false`. `cluster` is a group of single-point trips gathered by coordinate, returned only when `cluster_single_reports` was `true`.","properties":{"id":{"type":"integer","description":"Track ID. Present on `regular` and `single_report`, absent on `merged` and `cluster`."},"type":{"type":"string","description":"Which kind of track this is.","enum":["regular","single_report","merged","cluster"]},"start_date":{"type":"string","description":"Track start, in the user's time zone. On `single_report` it is when the point was registered."},"start_address":{"type":"string","description":"Address at the start."},"end_date":{"type":"string","description":"Track end, in the user's time zone. Absent on `single_report`."},"end_address":{"type":"string","description":"Address at the end. Absent on `single_report` and `cluster`."},"length":{"type":"number","description":"Track length in kilometres. Absent on `single_report` and `cluster`."},"points":{"description":"**One field name, two meanings, decided by `type`.** On `regular` and `merged` it is an integer, the total number of points in the track. On `cluster` it is a plain list of coordinates, the points gathered into the cluster, which is not the same thing as `points_list`. Absent on `single_report`.","oneOf":[{"type":"integer","description":"Total number of points in the track. `regular` and `merged`."},{"type":"array","description":"The coordinates gathered into this cluster. `cluster` only.","items":{"type":"object","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}]},"max_speed":{"type":"integer","description":"Highest speed recorded, in km/h. Absent on `single_report` and `cluster`."},"avg_speed":{"type":"integer","description":"Average speed in km/h. Absent on `cluster`."},"event_count":{"type":"integer","description":"Events recorded during the track. **Absent unless `count_events` was `true`.**"},"norm_fuel_consumed":{"type":"number","description":"Fuel consumed during the track, in litres. **Absent when no vehicle is linked to the tracker, or the vehicle has no `norm_avg_fuel_consumption`.**"},"precision":{"type":"integer","description":"Accuracy of the location in metres. Present on `single_report` and `cluster`, and depends on the device model."},"gsm_lbs":{"type":"boolean","description":"Optional. GSM LBS flag. On a `cluster` it is `true` only when every point in it is GSM LBS."},"points_list":{"type":"array","description":"The track points. **Returned only when `with_points` was `true`.**","items":{"$ref":"#/components/schemas/TrackPoint"}},"bounds":{"type":"object","description":"North-west and south-east corners of the axis-aligned minimum bounding box.","properties":{"nw":{"type":"object","description":"North-west corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"se":{"type":"object","description":"South-east corner.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}}}}}},"TrackPoint":{"type":"object","description":"One point recorded by a tracker, timestamped when the tracker recorded it and shown in the user's time zone.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"alt":{"type":"integer","description":"Altitude in metres."},"satellites":{"type":"integer","description":"How many GPS satellites fixed this point."},"mileage":{"type":"number","description":"Mileage."},"get_time":{"type":"string","description":"GPS timestamp of the point, in the user's time zone."},"address":{"type":"string","description":"Address at the point, or an empty string when none was recorded. **An address is recorded only at the start or end of a trip, or where an event happened.**"},"heading":{"type":"integer","description":"Direction in degrees, 0 to 360, where 0 is North.","minimum":0,"maximum":360},"speed":{"type":"integer","description":"Speed in km/h."},"precision":{"type":"integer","description":"Optional. Accuracy in metres. Depends on the device model."},"gsm_lbs":{"type":"boolean","description":"Optional. `true` when the location came from GSM LBS rather than GPS."},"parking":{"type":"boolean","description":"Optional. `true` when the point is not part of a trip. Which points count as parking depends on the platform's parking detection settings."},"buffered":{"type":"boolean","description":"Optional. `true` when the point was held in the device's memory and sent later. Varies by tracker model."}}},"TrackTotals":{"type":"object","description":"Totals across every track returned.","properties":{"count":{"type":"integer","description":"Number of tracks."},"length":{"type":"number","description":"Sum of all track lengths, in kilometres."},"trip_duration":{"type":"string","description":"Total time spent moving, as an ISO 8601 duration."},"parking_duration":{"type":"string","description":"Total time spent stationary, as an ISO 8601 duration. Measured across the whole requested period, so it includes the gaps before the first track and after the last."},"norm_fuel_consumed":{"type":"number","description":"Fuel consumed across all tracks, in litres. Omitted entirely when no track carries a figure."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/track/list":{"post":{"tags":["Tracks"],"summary":"List tracks","description":"Return the tracker's tracks over a period, with totals across all of them.\n\nWhat comes back depends on three switches. `split` decides whether the period is broken into separate trips or returned as one `merged` track. `cluster_single_reports` groups one-point trips by coordinate into `cluster` tracks. `filter` drops tracks judged too short by length and point count.\n\nPoints are left out unless `with_points` is set.","operationId":"trackList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.","minimum":1},"from":{"type":"string","description":"Start of the period, in `YYYY-MM-DD HH:MM:SS` format, in the account's timezone."},"to":{"type":"string","description":"End of the period, in `YYYY-MM-DD HH:MM:SS` format. Must be after `from`."},"filter":{"type":"boolean","description":"Optional. Default `true`. Drop tracks that are too short by length and number of points."},"split":{"type":"boolean","description":"Optional. Default `true`. When `false`, the whole period is returned as a single `merged` track."},"include_gsm_lbs":{"type":"boolean","description":"Optional. Default `true`. When `false`, GSM LBS points are excluded."},"cluster_single_reports":{"type":"boolean","description":"Optional. Default `false`. When `true`, one-point trips are grouped by coordinate into `cluster` tracks."},"count_events":{"type":"boolean","description":"Optional. Default `false`. When `true`, each track that is not a single point carries `event_count`."},"omit_addresses":{"type":"boolean","description":"Optional. Default `false`. When `true`, the address fields come back empty, which is faster."},"with_points":{"type":"boolean","description":"Optional. Default `false`. Include each track's `points_list`."},"point_limit":{"type":"integer","description":"Optional. Reduce the result to about this many points. Not a hard limit: the result can hold slightly more. Omit to use the platform's own simplification settings.","minimum":2,"maximum":3000}},"required":["tracker_id","from","to"]}}}},"responses":{"200":{"description":"The tracks","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","description":"Zero or more tracks. Empty means there were no trips matching the options, or the device sent no points.","items":{"$ref":"#/components/schemas/Track"}},"limit_exceeded":{"type":"boolean","description":"`true` when the requested period reaches further back than the tracker's plan allows. The period is silently clipped rather than refused, so a `true` here means the result covers less than was asked for."},"total":{"$ref":"#/components/schemas/TrackTotals"}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended. Error 211: the period between `from` and `to` exceeds the maximum the platform allows. Unlike the same code on `track/visit/list`, this one carries no `max_time_span`.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes): * 201 - Not found in the database. The tracker ID may match no tracker on the account the session hash belongs to. Check that the `tracker_id` and the hash belong to the same user. * 208 - Device blocked, when the tracker exists on the account but is inactive, whether through tariff restrictions or for another reason. * 211 - Requested time span is too big, when the interval between `from` and `to` exceeds the maximum the API configuration allows. *** ## Read track points > Return the individual points a tracker recorded over a period, or the points of one track.\ > \ > Each point's timestamp is when the tracker recorded it, converted to the account's timezone.\ > \ > Reachable from a geo-link session as well as an ordinary one. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tracks","description":"The trips a tracker made, the points behind them, the geofences and places they passed through, and waybills built from them. All resources under the /track/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"TrackPoint":{"type":"object","description":"One point recorded by a tracker, timestamped when the tracker recorded it and shown in the user's time zone.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"alt":{"type":"integer","description":"Altitude in metres."},"satellites":{"type":"integer","description":"How many GPS satellites fixed this point."},"mileage":{"type":"number","description":"Mileage."},"get_time":{"type":"string","description":"GPS timestamp of the point, in the user's time zone."},"address":{"type":"string","description":"Address at the point, or an empty string when none was recorded. **An address is recorded only at the start or end of a trip, or where an event happened.**"},"heading":{"type":"integer","description":"Direction in degrees, 0 to 360, where 0 is North.","minimum":0,"maximum":360},"speed":{"type":"integer","description":"Speed in km/h."},"precision":{"type":"integer","description":"Optional. Accuracy in metres. Depends on the device model."},"gsm_lbs":{"type":"boolean","description":"Optional. `true` when the location came from GSM LBS rather than GPS."},"parking":{"type":"boolean","description":"Optional. `true` when the point is not part of a trip. Which points count as parking depends on the platform's parking detection settings."},"buffered":{"type":"boolean","description":"Optional. `true` when the point was held in the device's memory and sent later. Varies by tracker model."}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/track/read":{"post":{"tags":["Tracks"],"summary":"Read track points","description":"Return the individual points a tracker recorded over a period, or the points of one track.\n\nEach point's timestamp is when the tracker recorded it, converted to the account's timezone.\n\nReachable from a geo-link session as well as an ordinary one.","operationId":"trackRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.","minimum":1},"from":{"type":"string","description":"Start of the period, in `YYYY-MM-DD HH:MM:SS` format, in the account's timezone."},"to":{"type":"string","description":"End of the period, in `YYYY-MM-DD HH:MM:SS` format. Must be after `from`."},"track_id":{"type":"integer","description":"Optional. Return only the points of this track. Omit to return every valid point in the period.","minimum":1},"include_gsm_lbs":{"type":"boolean","description":"Optional. Default `true`. When `false` **and no `track_id` is given**, GSM LBS points are excluded."},"simplify":{"type":"boolean","description":"Optional. Default `true`. Reduce the number of points returned."},"point_limit":{"type":"integer","description":"Optional. Reduce the result to about this many points. Not a hard limit: the result can hold slightly more. Omit to use the platform's own simplification settings.","minimum":2,"maximum":3000},"filter":{"type":"boolean","description":"Optional. Default `true`. Filter the points, which currently affects LBS tracks only. Setting it to `false` also brings parking points into the result."}},"required":["tracker_id","from","to"]}}}},"responses":{"200":{"description":"The track points","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/TrackPoint"}},"limit_exceeded":{"type":"boolean","description":"`true` when the requested period reaches further back than the tracker's plan allows. The period is silently clipped rather than refused, so a `true` here means the result covers less than was asked for."}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended. Error 211: the period between `from` and `to` exceeds the maximum the platform allows. Unlike the same code on `track/visit/list`, this one carries no `max_time_span`.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes): * 201 - Not found in the database. The tracker ID may match no tracker on the account the session hash belongs to. Check that the `tracker_id` and the hash belong to the same user. * 208 - Device blocked, when the tracker exists on the account but is inactive, whether through tariff restrictions or for another reason. * 211 - Requested time span is too big, when the interval between `from` and `to` exceeds the maximum the API configuration allows. ## Visits `track/visit/list` answers a different question from the operations above: not where the tracker went, but which of the account's geofences and places it was inside during the period. *** ## List visited geofences and places > Return the IDs of the geofences and places that contain at least one of the tracker's points in the period.\ > \ > Both lists come back empty when the account has no geofences and no places, and each is empty when its \`include\_\` switch is \`false\`.\ > \ > \*\*This call has its own period limit\*\*, separate from the one the other track calls use, and it is usually shorter. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tracks","description":"The trips a tracker made, the points behind them, the geofences and places they passed through, and waybills built from them. All resources under the /track/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/track/visit/list":{"post":{"tags":["Tracks"],"summary":"List visited geofences and places","description":"Return the IDs of the geofences and places that contain at least one of the tracker's points in the period.\n\nBoth lists come back empty when the account has no geofences and no places, and each is empty when its `include_` switch is `false`.\n\n**This call has its own period limit**, separate from the one the other track calls use, and it is usually shorter.","operationId":"trackVisitList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account and not be blocked.","minimum":1},"from":{"type":"string","description":"Start of the period, in `YYYY-MM-DD HH:MM:SS` format, in the account's timezone."},"to":{"type":"string","description":"End of the period, in `YYYY-MM-DD HH:MM:SS` format. Must be after `from`."},"include_zones":{"type":"boolean","description":"Optional. Default `true`. When `false`, `zones` comes back empty."},"include_places":{"type":"boolean","description":"Optional. Default `true`. When `false`, `places` comes back empty."}},"required":["tracker_id","from","to"]}}}},"responses":{"200":{"description":"The visited geofences and places","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"value":{"type":"object","properties":{"zones":{"type":"array","description":"IDs of the geofences visited.","items":{"type":"integer"}},"places":{"type":"array","description":"IDs of the places visited.","items":{"type":"integer"}}}}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 208: the tracker exists but is blocked, normally because its tariff ended. Error 211: the period exceeds this call's own maximum, which is much shorter than the one the other track calls use. The response body carries `max_time_span`, **a human-readable English string such as `26 hours`, not an ISO 8601 duration**.","$ref":"#/components/responses/ResponseError"},"404":{"description":"Error 204: no tracker with this ID belongs to the current account.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes): * 204 - Entity not found. The tracker ID may match no tracker on the account the session hash belongs to. Check that the `tracker_id` and the hash belong to the same user. ## More in this section #### Waybill | Endpoint | Method | What it does | | ---------------------------------------------------------------------------------------------------------------------- | ------ | ---------------- | | [`/track/waybill/download`](/docs/navixy-api/user-api/resources/tracking/track/waybill.md#post-track-waybill-download) | POST | Download waybill | #### Waybill settings | Endpoint | Method | What it does | | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------ | | [`/track/waybill/settings/read`](/docs/navixy-api/user-api/resources/tracking/track/waybill/settings.md#post-track-waybill-settings-read) | POST | Read last waybill number | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/navixy-api/user-api/resources/tracking/track.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.