Skip to content

Commit 56eacb7

Browse files
author
Daria Mitrofanova
committed
Supplement Asset doc
1 parent 98f3d2c commit 56eacb7

File tree

1 file changed

+172
-123
lines changed
  • docs/backend-api/resources/tracking/asset

1 file changed

+172
-123
lines changed

‎docs/backend-api/resources/tracking/asset/index.md

+172-123
Original file line numberDiff line numberDiff line change
@@ -52,25 +52,24 @@ settings will provide us with necessary info by default.
5252

5353
```json
5454
{
55-
"success": true,
56-
"list": [
57-
{
58-
"tracker_id": 2793258,
59-
"limit_exceeded": false,
60-
"interval": {
61-
"from": "2023-11-01 03:00:00",
62-
"to": "2023-11-30 03:00:00"
63-
},
64-
"tracks": [track_info]
65-
}
66-
]
55+
"success": true,
56+
"list": [
57+
{
58+
"tracker_id": 2793258,
59+
"limit_exceeded": false,
60+
"interval": {
61+
"from": "2023-11-01 03:00:00",
62+
"to": "2023-11-30 03:00:00"
63+
},
64+
"tracks": [track_info]
65+
}
66+
]
6767
}
6868
```
6969

7070
* `tracker_id` - int. Tracker identifier.
7171
* `limit_exceeded` - boolean. It will be `true` if the requested time period surpasses the limit set in the tracker's tariff.
72-
For instance, if the device's plan has a maximum storage period of three months (the default value), and we request trips
73-
for six months.
72+
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.
7473
* `from` - [date/time](../../../getting-started.md#data-types). This is timestamp of the start of the interval when the asset was attached to the tracker.
7574
* `to` - [date/time](../../../getting-started.md#data-types). This is timestamp of the end of the interval when the asset was attached to the tracker.
7675
* `tracks` - an array of JSON objects containing track information.
@@ -81,123 +80,166 @@ where `track_info` is either `regular`, `single_report`, `merged` or `cluster`:
8180

8281
```json
8382
{
84-
"id": 123456,
85-
"start_date": "2023-11-23 03:39:44",
86-
"start_address": "1255 6th Ave, New York, NY 10020, USA",
87-
"max_speed": 62,
88-
"end_date": "2023-11-23 06:39:44",
89-
"end_address": "888 5th Ave, New York, NY 10021, USA",
90-
"length": 5.5,
91-
"points": 327,
92-
"avg_speed": 49,
93-
"event_count": 3,
94-
"norm_fuel_consumed": 1.07,
95-
"type": "regular",
96-
"gsm_lbs": false
83+
"id": 123456,
84+
"start_date": "2023-11-23 03:39:44",
85+
"start_address": "1255 6th Ave, New York, NY 10020, USA",
86+
"max_speed": 62,
87+
"end_date": "2023-11-23 06:39:44",
88+
"end_address": "888 5th Ave, New York, NY 10021, USA",
89+
"length": 5.5,
90+
"points": 327,
91+
"avg_speed": 49,
92+
"event_count": 3,
93+
"norm_fuel_consumed": 1.07,
94+
"type": "regular",
95+
"gsm_lbs": false,
96+
"points_list": [point_info],
97+
"bounds": {
98+
"nw": {
99+
"lat": 57.151005,
100+
"lng": 59.92729333
101+
},
102+
"se": {
103+
"lat": 56.47945333,
104+
"lng": 61.19021833
105+
}
106+
}
97107
}
98108
```
99109

100110
* `id` - int. Track id.
101-
* `start_date` - [date/time](../../../getting-started.md#data-types). Track start date, in user's timezone e.g. "2011-06-18 03:39:44".
111+
* `start_date` - [date/time](../../../getting-started.md#data-types). Track start date, in user's timezone.
102112
* `start_address` - string. Track start address.
103-
* `max_speed` - int. Maximum speed registered during track in km/h, e.g. 96.
104-
* `end_date` - [date/time](../../../getting-started.md#data-types). Track end date, in user's timezone e.g. "2011-06-18 05:18:36".
113+
* `max_speed` - int. Maximum speed registered during track in km/h.
114+
* `end_date` - [date/time](../../../getting-started.md#data-types). Track end date, in user's timezone.
105115
* `end_address` - string. Track end address.
106-
* `length` - float. Track length in kilometers, e.g. 85.5.
107-
* `points` - int. Total number of points in a track, e.g. 724.
108-
* `avg_speed` - int. Average speed in km/h, e.g. 70.
109-
* `event_count` - int. It represents the number of events recorded during this track. This field will not be present if "count_events" is set to `false`.
110-
* `norm_fuel_consumed` - float. It is representing the amount of fuel consumed during the track, measured
111-
in litres. This field will not be present if there's no [vehicle_object](../../fleet/vehicle/index.md#vehicle) linked to the
112-
tracker or if "normAvgFuelConsumption" is not defined for the linked vehicle object.
113-
* `type` - [enum](../../../getting-started.md#data-types) with possible values: `regular`, `single_report`, `merged`, `cluster`.
114-
It's used to differentiate this regular track type from other types.
116+
* `length` - float. Track length in kilometers.
117+
* `points` - int. Total number of points in a track.
118+
* `avg_speed` - int. Average speed in km/h.
119+
* `event_count` - int. Number of events recorded during this track. This field will not be present if "count_events" is set to `false`.
120+
* `norm_fuel_consumed` - float. Amount of fuel consumed during the track, measured in litres.
121+
This field will not be present if there's no [vehicle_object](../../fleet/vehicle/index.md#vehicle) linked to the tracker or
122+
if "normAvgFuelConsumption" is not defined for the linked vehicle object.
123+
* `type` - [enum](../../../getting-started.md#data-types): `regular`, `single_report`, `merged`, `cluster`. Track type.
115124
* `gsm_lbs` - optional boolean. GSM LBS point flag.
125+
* `points_list` - array of JSON objects. A list of [point info](#point-info).
126+
* `bounds` - object. North-west and south-east coordinates of the bounding box that contains all points.
116127

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

120131
```json
121132
{
122-
"id": 123456,
123-
"start_date": "2023-11-24 03:39:44",
124-
"start_address": "1255 6th Ave, New York, NY 10020, USA",
125-
"avg_speed": 34,
126-
"gsm_lbs": false,
127-
"type": "single_report",
128-
"precision": 10
133+
"id": 123456,
134+
"start_date": "2023-11-24 03:39:44",
135+
"start_address": "1255 6th Ave, New York, NY 10020, USA",
136+
"avg_speed": 34,
137+
"gsm_lbs": false,
138+
"type": "single_report",
139+
"precision": 10,
140+
"points_list": [point_info]
129141
}
130142
```
131143

132144
* `id` - int. Track id.
133-
* `start_date` - [date/time](../../../getting-started.md#data-types). It represents the date and time when the tracker registered the point, adjusted to
134-
the user's timezone, for example, "2011-06-18 03:39:44".
145+
* `start_date` - [date/time](../../../getting-started.md#data-types). Date when the tracker registered the point, in user's timezone.
135146
* `start_address` - string. Point address.
136-
* `avg_speed` - int. Average speed in km/h, e.g. 70.
147+
* `avg_speed` - int. Average speed in km/h.
137148
* `gsm_lbs` - optional boolean. GSM LBS point flag.
138-
* `type` - [enum](../../../getting-started.md#data-types): `regular`, `single_report`, `merged`, `cluster`.
139-
Used to distinguish this track type (`single_report`) from the others.
140-
* `precision` - optional int. It signifies the precision of the location in meters. Its presence relies on the device model.
149+
* `type` - [enum](../../../getting-started.md#data-types): `regular`, `single_report`, `merged`, `cluster`. Track type.
150+
* `precision` - optional int. Precision of the location in meters. Its presence relies on the device model.
151+
* `points_list` - array of JSON objects. A list of [point info](#point-info).
141152

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

144155
```json
145156
{
146-
"start_date": "2023-11-24 03:39:44",
147-
"start_address": "1255 6th Ave, New York, NY 10020, USA",
148-
"max_speed": 62,
149-
"end_date": "2023-11-24 06:39:44",
150-
"end_address": "888 5th Ave, New York, NY 10021, USA",
151-
"length": 5.5,
152-
"points": 327,
153-
"avg_speed": 49,
154-
"event_count": 3,
155-
"norm_fuel_consumed": 1.07,
156-
"type": "merged",
157-
"gsm_lbs": false
157+
"start_date": "2023-11-24 03:39:44",
158+
"start_address": "1255 6th Ave, New York, NY 10020, USA",
159+
"max_speed": 62,
160+
"end_date": "2023-11-24 06:39:44",
161+
"end_address": "888 5th Ave, New York, NY 10021, USA",
162+
"length": 5.5,
163+
"points": 327,
164+
"avg_speed": 49,
165+
"event_count": 3,
166+
"norm_fuel_consumed": 1.07,
167+
"type": "merged",
168+
"gsm_lbs": false,
169+
"points_list": [point_info],
170+
"bounds": {
171+
"nw": {
172+
"lat": 57.151005,
173+
"lng": 59.92729333
174+
},
175+
"se": {
176+
"lat": 56.47945333,
177+
"lng": 61.19021833
178+
}
179+
}
158180
}
159181
```
160182

161-
* `start_date` - [date/time](../../../getting-started.md#data-types). Track start date, in user's timezone e.g. "2011-06-18 03:39:44". It signifies the
162-
initial point identified as a track for a specified time period.
183+
* `start_date` - [date/time](../../../getting-started.md#data-types). Track start date, in user's timezone.
184+
It signifies the initial point identified as a track for a specified time period.
163185
* `start_address` - string. Track start address.
164-
* `max_speed` - int. Maximum speed registered during period in km/h, e.g. 96.
165-
* `end_date` - [date/time](../../../getting-started.md#data-types). Track end date, in user's timezone e.g. "2011-06-18 05:18:36". It signifies the
166-
last point identified as a track for a specified time period.
186+
* `max_speed` - int. Maximum speed registered during period in km/h.
187+
* `end_date` - [date/time](../../../getting-started.md#data-types). Track end date, in user's timezone.
188+
It signifies the last point identified as a track for a specified time period.
167189
* `end_address` - string. Track end address.
168-
* `length` - float. Track length during period in kilometers, e.g. 85.5.
169-
* `points` - int. Total number of points in a track, e.g. 724.
170-
* `avg_speed` - int. Average speed in km/h, e.g. 70.
171-
* `event_count` - int. It represents the number of events recorded during this track. This field will not be present if "count_events" is set to `false`.
172-
* `norm_fuel_consumed` - float. It is representing the amount of fuel consumed during the track, measured
173-
in litres. This field will not be present if there's no [vehicle_object](../../fleet/vehicle/index.md#vehicle) linked to the
174-
tracker or if "normAvgFuelConsumption" is not defined for the linked vehicle object.
175-
* `type` - [enum](../../../getting-started.md#data-types): `regular`, `single_report`, `merged`, `cluster`.
176-
Used to distinguish this track type (`merged`) from the others.
177-
* `gsm_lbs` - optional boolean. GSM LBS flag.
190+
* `length` - float. Track length in kilometers.
191+
* `points` - int. Total number of points in a track.
192+
* `avg_speed` - int. Average speed in km/h.
193+
* `event_count` - int. Number of events recorded during period. This field will not be present if "count_events" is set to `false`.
194+
* `norm_fuel_consumed` - float. Amount of fuel consumed during period, measured in litres.
195+
This field will not be present if there's no [vehicle_object](../../fleet/vehicle/index.md#vehicle) linked to the tracker or
196+
if "normAvgFuelConsumption" is not defined for the linked vehicle object.
197+
* `type` - [enum](../../../getting-started.md#data-types): `regular`, `single_report`, `merged`, `cluster`. Track type.
198+
* `gsm_lbs` - optional boolean. GSM LBS point flag.
199+
* `points_list` - array of JSON objects. A list of [point info](#point-info).
200+
* `bounds` - object. North-west and south-east coordinates of the bounding box that contains all points.
178201

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

181204
```json
182205
{
183-
"start_date": "2023-11-24 03:39:44",
184-
"start_address": "1255 6th Ave, New York, NY 10020, USA",
185-
"end_date": "2020-09-24 06:39:44",
186-
"precision": 500,
187-
"points": [{"lat": 34.178868, "lng": -118.599672}, {"lat": 31.738386, "lng": -106.453854}],
188-
"type": "cluster",
189-
"gsm_lbs": false
206+
"start_date": "2023-11-24 03:39:44",
207+
"start_address": "1255 6th Ave, New York, NY 10020, USA",
208+
"end_date": "2020-09-24 06:39:44",
209+
"precision": 500,
210+
"points": [
211+
{
212+
"lat": 34.178868,
213+
"lng": -118.599672
214+
},
215+
{
216+
"lat": 31.738386,
217+
"lng": -106.453854
218+
}
219+
],
220+
"bounds": {
221+
"nw": {
222+
"lat": 57.151005,
223+
"lng": 59.92729333
224+
},
225+
"se": {
226+
"lat": 56.47945333,
227+
"lng": 61.19021833
228+
}
229+
},
230+
"type": "cluster",
231+
"gsm_lbs": false
190232
}
191233
```
192234

193-
* `start_date` - [date/time](../../../getting-started.md#data-types). Track start date, in user's timezone e.g. "2011-06-18 03:39:44".
235+
* `start_date` - [date/time](../../../getting-started.md#data-types). Track start date, in user's timezone.
194236
* `start_address` - string. Track start address.
195-
* `end_date` - [date/time](../../../getting-started.md#data-types). Track end date, in user's timezone e.g. "2011-06-18 05:18:36".
196-
* `precision` - optional int. It signifies the precision of the location in meters. Its presence relies on the device model.
237+
* `end_date` - [date/time](../../../getting-started.md#data-types). Track end date, in user's timezone.
238+
* `precision` - optional int. Precision of the location in meters. Its presence relies on the device model.
197239
* `points` - array of point objects in a cluster.
198-
* `type` - [enum](../../../getting-started.md#data-types): `regular`, `single_report`, `merged`, `cluster`.
199-
Used to distinguish this track type (`cluster`) from the others.
200-
* `gsm_lbs` - optional boolean. GSM LBS flag. If a cluster only contains GSM LBS points, then this value will be set to `true`.
240+
* `type` - [enum](../../../getting-started.md#data-types): `regular`, `single_report`, `merged`, `cluster`. Track type.
241+
* `gsm_lbs` - optional boolean. GSM LBS flag. `true` if a cluster contains only GSM LBS points.
242+
* `bounds` - object. North-west and south-east coordinates of the bounding box that contains all points.
201243

202244
#### errors
203245

@@ -242,47 +284,54 @@ are `true`, we should list them in our request.
242284

243285
```json
244286
{
245-
"success": true,
246-
"list": [
247-
{
248-
"tracker_id": 2793258,
249-
"limit_exceeded": false,
250-
"interval": {
251-
"from": "2023-11-01 03:00:00",
252-
"to": "2023-11-01 23:00:00"
253-
},
254-
"track_points": [
255-
{
256-
"lat": 43.0375133,
257-
"lng": -79.226505,
258-
"alt": 0,
259-
"satellites": 10,
260-
"mileage": 43.93,
261-
"get_time": "2023-11-01 04:38:39",
262-
"address": "Kottmeier Road, Thorold, Golden Horseshoe, Ontario, Canada, L3B 5N6",
263-
"heading": 280,
264-
"speed": 53,
265-
"precision": 100,
266-
"gsm_lbs": false,
267-
"parking": false,
268-
"buffered": true
269-
}
270-
]
271-
}
272-
]
287+
"success": true,
288+
"list": [
289+
{
290+
"tracker_id": 2793258,
291+
"limit_exceeded": false,
292+
"interval": {
293+
"from": "2023-11-01 03:00:00",
294+
"to": "2023-11-01 23:00:00"
295+
},
296+
"track_points": [point_info]
297+
}
298+
]
273299
}
274300
```
275301

276302
* `tracker_id` - int. Tracker identifier.
277303
* `limit_exceeded` - boolean. It will be `true` if the requested time period surpasses the limit set in the tracker's tariff.
278-
For instance, if the device's plan has a maximum storage period of three months (the default value), and we request trips
279-
for six months.
304+
For instance, if the device's plan has a maximum storage period of three months (the default value), and we request trips
305+
for six months.
280306
* `from` - [date/time](../../../getting-started.md#data-types). This is timestamp of the start of the interval when the asset was attached to the tracker.
281307
* `to` - [date/time](../../../getting-started.md#data-types). This is timestamp of the end of the interval when the asset was attached to the tracker.
308+
* `track_points` - array of JSON objects. A list of [point info](#point-info).
309+
310+
#### point info
311+
312+
```json
313+
{
314+
"lat": 43.0375133,
315+
"lng": -79.226505,
316+
"alt": 0,
317+
"satellites": 10,
318+
"mileage": 43.93,
319+
"get_time": "2023-11-01 04:38:39",
320+
"address": "Kottmeier Road, Thorold, Golden Horseshoe, Ontario, Canada, L3B 5N6",
321+
"heading": 280,
322+
"speed": 53,
323+
"precision": 100,
324+
"gsm_lbs": false,
325+
"parking": false,
326+
"buffered": true
327+
}
328+
```
329+
282330
* `lat` - float. Represents latitude.
283331
* `lng` - float. Represents longitude.
284332
* `alt` - int. Indicates the altitude in meters.
285333
* `satellites` - int. Shows the number of GPS satellites used to determine this point.
334+
* `mileage` - float. Represents mileage.
286335
* `get_time` - [date/time](../../../getting-started.md#data-types). This is the GPS timestamp of the point, adjusted to the user's timezone.
287336
* `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.
288337
* `heading` - int. A value that represents the direction in degrees, with a range of 0 to 360. 0 corresponds to North.
@@ -296,4 +345,4 @@ are `true`, we should list them in our request.
296345

297346
* 201 - Not found in database – The asset with ID from your request does not exist.
298347
* 211 - Requested time span is too big – If the interval between the "from" and "to" dates is too large, it may exceed
299-
the maximum value defined in the API configuration.
348+
the maximum value defined in the API configuration.

0 commit comments

Comments
 (0)