> 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/asset.md). # Asset Tracks for an asset, resolved across every tracker the asset was attached to over the period. An asset is tracked through whichever device is attached to it at the time, and that device can change. These operations take an asset and resolve its trackers, which is what separates them from `track/*`, where the caller supplies tracker IDs directly. Each entry in a response carries its own `interval`: the window during which the asset was attached to that tracker, not the window the request asked for. An asset moved between devices mid-period therefore comes back as several entries. A track arrives as one of four kinds, selected by its `type`. `regular` is an ordinary trip. `single_report` covers a device reporting in interval mode, or a period holding only one point. `merged` is the whole period as one track, returned when `split` was `false`. `cluster` groups one-point trips by coordinate, returned when `cluster_single_reports` was `true`. ## Point object The point object both operations return, in `points_list` on a track and in `track_points` on a read: ## 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: `/asset/track`. *** ## List asset tracks > Return the tracks of an asset over a period, one entry per tracker the asset was attached to.\ > \ > Each entry carries its own \`interval\`, which is the window during which the asset was attached to that tracker, not the window you asked for.\ > \ > This is the \*\*asset\*\* track resource, \`asset/track/\*\`, which takes an asset and resolves its trackers for you. It is a different resource from \`track/\*\`, which takes tracker IDs directly.\ > \ > A request with an empty body reports \`interval\` as a missing parameter alongside \`asset\`. That is the internal name of the field holding both dates; the public parameters are \`from\` and \`to\`. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Tracks belonging to an asset rather than to a tracker, and the groups assets are organised into. All resources under the /asset/track/ and /asset_group/ paths."}],"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":{"/asset/track/list":{"post":{"tags":["Assets"],"summary":"List asset tracks","description":"Return the tracks of an asset over a period, one entry per tracker the asset was attached to.\n\nEach entry carries its own `interval`, which is the window during which the asset was attached to that tracker, not the window you asked for.\n\nThis is the **asset** track resource, `asset/track/*`, which takes an asset and resolves its trackers for you. It is a different resource from `track/*`, which takes tracker IDs directly.\n\nA request with an empty body reports `interval` as a missing parameter alongside `asset`. That is the internal name of the field holding both dates; the public parameters are `from` and `to`.","operationId":"assetTrackList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","description":"Which asset to report on. The tracker list is derived from the trackers currently related to this asset.","properties":{"id":{"type":"integer","description":"ID of the asset."},"type":{"type":"string","description":"What kind of asset it is.","enum":["vehicle","employee"]}}},"from":{"type":"string","description":"Start of the period. The response begins with the next track point after this time."},"to":{"type":"string","description":"End of the period. Must be later than `from`."},"filter":{"type":"boolean","description":"Optional. Default `true`. Drop tracks judged too short by length and point count."},"split":{"type":"boolean","description":"Optional. Default `true`. When `false`, all tracks in the period are combined into one, returned as a `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`, single-point trips are grouped by coordinates into `cluster` tracks."},"count_events":{"type":"boolean","description":"Optional. Default `false`. When `true`, each multi-point track carries `event_count`."},"omit_addresses":{"type":"boolean","description":"Optional. Default `false`. When `true`, address fields come back empty."},"with_points":{"type":"boolean","description":"Optional. Default `false`. When `true`, each track carries its `points_list`."},"point_limit":{"type":"integer","description":"Optional. Reduce the returned points to about this many, from 2 to 3000. Without it the server's own simplification settings apply. **Not a hard limit**: the response may contain more.","minimum":2,"maximum":3000}},"required":["asset","from","to"]}}}},"responses":{"200":{"description":"The asset's tracks, per tracker","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"Tracker identifier."},"limit_exceeded":{"type":"boolean","description":"`true` when the requested period is longer than the tracker's plan stores, so the data is truncated."},"interval":{"type":"object","description":"When the asset was attached to this tracker, which is not necessarily the period requested.","properties":{"from":{"type":"string","description":"Start of the attachment interval."},"to":{"type":"string","description":"End of the attachment interval."}}},"tracks":{"type":"array","items":{"$ref":"#/components/schemas/Track"}}}}},"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 211: the period between `from` and `to` is longer than the API configuration allows.","$ref":"#/components/responses/ResponseError"},"404":{"description":"Error 201: the asset in the request does not exist. The description names it, for example \"Employee #1 not found\".","$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, when no asset has the given ID. * 211 - Requested time span is too big, when the interval between `from` and `to` exceeds the maximum the API configuration allows. *** The timestamp on each point is the moment the tracker recorded it, adjusted to the user's time zone. ## Read asset track points > Return the individual track points recorded for an asset over a period, one entry per tracker the asset was attached to.\ > \ > Each point's timestamp is when the tracker recorded it, in the user's time zone.\ > \ > This is the \*\*asset\*\* track resource, \`asset/track/\*\`, which takes an asset and resolves its trackers for you. It is a different resource from \`track/\*\`, which takes tracker IDs directly.\ > \ > A request with an empty body reports \`interval\` as a missing parameter alongside \`asset\`. That is the internal name of the field holding both dates; the public parameters are \`from\` and \`to\`. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Assets","description":"Tracks belonging to an asset rather than to a tracker, and the groups assets are organised into. All resources under the /asset/track/ and /asset_group/ paths."}],"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":{"/asset/track/read":{"post":{"tags":["Assets"],"summary":"Read asset track points","description":"Return the individual track points recorded for an asset over a period, one entry per tracker the asset was attached to.\n\nEach point's timestamp is when the tracker recorded it, in the user's time zone.\n\nThis is the **asset** track resource, `asset/track/*`, which takes an asset and resolves its trackers for you. It is a different resource from `track/*`, which takes tracker IDs directly.\n\nA request with an empty body reports `interval` as a missing parameter alongside `asset`. That is the internal name of the field holding both dates; the public parameters are `from` and `to`.","operationId":"assetTrackRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset":{"type":"object","description":"Which asset to report on. The tracker list is derived from the trackers currently related to this asset.","properties":{"id":{"type":"integer","description":"ID of the asset."},"type":{"type":"string","description":"What kind of asset it is.","enum":["vehicle","employee"]}}},"from":{"type":"string","description":"Start of the period. The response begins with the next track point after this time."},"to":{"type":"string","description":"End of the period. Must be later than `from`."},"track_id":{"type":"integer","description":"Optional. Return only the points of this track. Without it, every valid track point in the period is returned."},"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`. When `true`, the returned data is simplified to fewer points."},"point_limit":{"type":"integer","description":"Optional. Only applies when `simplify` is `true`. Reduce the returned points to about this many, from 2 to 3000. **Not a hard limit**: the response may contain more.","minimum":2,"maximum":3000},"filter":{"type":"boolean","description":"Optional. When `true`, tracks are filtered, which currently affects LBS tracks only. When `false`, parking points are included."}},"required":["asset","from","to"]}}}},"responses":{"200":{"description":"The asset's track points, per tracker","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"Tracker identifier."},"limit_exceeded":{"type":"boolean","description":"`true` when the requested period is longer than the tracker's plan stores."},"interval":{"type":"object","description":"When the asset was attached to this tracker.","properties":{"from":{"type":"string","description":"Start of the attachment interval."},"to":{"type":"string","description":"End of the attachment interval."}}},"track_points":{"type":"array","items":{"$ref":"#/components/schemas/TrackPoint"}}}}}}}}}},"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 211: the period between `from` and `to` is longer than the API configuration allows.","$ref":"#/components/responses/ResponseError"},"404":{"description":"Error 201: the asset in the request does not exist.","$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, when no asset has the given ID. * 211 - Requested time span is too big, when the interval between `from` and `to` exceeds the maximum the API configuration allows. ## More in this section #### Asset groups | Endpoint | Method | What it does | | ------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------ | | [`/asset_group/create`](/docs/navixy-api/user-api/resources/tracking/asset/asset-groups.md#post-asset_group-create) | POST | Create asset group | | [`/asset_group/list`](/docs/navixy-api/user-api/resources/tracking/asset/asset-groups.md#post-asset_group-list) | POST | List asset groups | | [`/asset_group/set`](/docs/navixy-api/user-api/resources/tracking/asset/asset-groups.md#post-asset_group-set) | POST | Set assets in group | | [`/asset_group/remove`](/docs/navixy-api/user-api/resources/tracking/asset/asset-groups.md#post-asset_group-remove) | POST | Remove assets from group | | [`/asset_group/update`](/docs/navixy-api/user-api/resources/tracking/asset/asset-groups.md#post-asset_group-update) | POST | Rename asset group | | [`/asset_group/delete`](/docs/navixy-api/user-api/resources/tracking/asset/asset-groups.md#post-asset_group-delete) | POST | Delete asset group | --- # 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/asset.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.