- Have any questions?
- 0161 914 5500
- [email protected]
Basic Concepts
January 8, 2018Data Concepts
March 2, 2018This section details a number of reports that are available as standard. This gives a flavour of the data that is available via the API. The system has significantly more reports than those detailed here. We also provide bespoke data extraction calls if you need access to business specific device data.
Calls in this section (apart from historic) return data in an unnormalised form. Each call has a specific return dataset, this is detailed in each section.
Calls in this section include
Detailed
This call can return both overview and detailed data. Setting levelOfDetail=0 returns overview data, and levelOfDetail=1 will return very fine grained detailed data.
- Overview data (levelOfDetail=0) contains a summary per day for each vehicle.
- Detailed data (levelOfDetail=1) returns all data for the given vehicle and time range.
Note that when the levelOfDetail is set to 1 it is not possible to filter by eventID. It may be more appropriate to use the Historic report if this is required. The Historic is normally better for display of vehicle on a map.
Query Parameters
| Parameter | Values | Notes |
| op | Report | Required |
| subop | Detailed | Required |
| startDate | {number in format YYYYMMDD} | Required, report from the start of this day |
| endDate | {number in format YYYYMMDD} | Required, report to the start of this day |
| vehicleIDs | {comma delimited list of ids or 0 for wildcard} | Required |
| groupIDs | {comma delimited list of ids or 0 for wildcard} | Required |
| levelOfDetail | {0 or 1, 0 is overview 1 is detail} | Required |
startDate and endDate mark the start of a day. To report on a single day endDate must be set to the next day. For example, 20200312 and 20200313
Response (levelofdetail=0)
The return data is a summary per day for all vehicles reported on.
{
"version":"0.6",
"reqId":"",
"status":"ok",
"sig":"-1874477413",
"dataset":{
"datasetname":"Report_Detailed",
"tables":[
{
"cols":[
{
"id":"0",
"label":"Grouping",
"type":"datetime",
"p":{}
},
{
"id":"1",
"label":"IgnitionOnTimeSecs",
"type":"number",
"p":{}
},
{
"id":"2",
"label":"MovingTimeSecs",
"type":"number",
"p":{}
},
{
"id":"3",
"label":"IdlingTimeSecs",
"type":"number",
"p":{}
},
{
"id":"4",
"label":"DisTravelledKms",
"type":"number",
"p":{}
},
{
"id":"5",
"label":"DistanceCost",
"type":"number",
"p":{}
},
{
"id":"6",
"label":"HourCost",
"type":"number",
"p":{}
},
{
"id":"7",
"label":"TotalCost",
"type":"number",
"p":{}
}
],
"rows":[...
Fields to note:
- Grouping – datetime of the start of the particular day
- IgnitionOnTimeSecs – ignition on time in secs
- MovingTimeSecs – non-idling time in secs
- IdlingTimeSecs – idling time in secs
- DistanceTravelledKm – distance travelled in km
- DistanceCost – distance cost in cost units
- HourCost – time cost in cost units
- TotalCost – DistanceCost+HourCost
Response (levelofdetail=1)
The return data includes all data for all vehicles. As every record is returned for each vehicle reported on, this can result in a huge amount of data. To avoid timeouts, ideally report on a single vehicle for a single day.
{
"version":"0.6",
"reqId":"",
"status":"ok",
"sig":"583999281",
"dataset":{
"datasetname":"Report_Detailed",
"tables":[
{
"cols":[
{
"id":"0",
"label":"Description",
"type":"string",
"p":{}
},
{
"id":"1",
"label":"Registration",
"type":"string",
"p":{}
},
{
"id":"2",
"label":"GPSDateTime",
"p":{}
},
{
"id":"3",
"label":"Longitude",
"type":"number",
"p":{}
},
{
"id":"4",
"label":"Latitude",
"type":"number",
"p":{}
},
{
"id":"5",
"label":"EventID",
"type":"number",
"p":{}
},
{
"id":"6",
"label":"DistanceKm",
"type":"number",
"p":{}
},
{
"id":"7",
"label":"SpeedKph",
"type":"number",
"p":{}
},
{
"id":"8",
"label":"PlaceName",
"type":"string",
"p":{}
},
{
"id":"9",
"label":"Parameter",
"type":"string",
"p":{}
}
],
"rows":[...
- Description – vehicle Description
- Registration – vehicle Registration
- GPSDateTime – UTC GPS Datetime
- Longitude – gps longitude
- Latitude – gps latitude
- EventID – the vehicle event
- DistanceKm – only valid on starts, then shows distance until next stop
- SpeedKph – vehicle speed
- PlaceName – if vehicle is in a client ‘Place’
- Parameter – JSON payload containing other payload
Historical
This report is most useful when displaying data on a map. It is possible to return granular data from set start and endpoints, filtered by events.
Each record in the result set contains a valid GPS fix along with other payload in either the ‘Tag’ or ‘Parameter’ field. The payload will be dependent on the EventID. If you find a payload you don’t understand, please get in touch and we’ll let you know what you are looking at.
Query Parameters
| Parameter | Values | Notes |
| op | Report | Required |
| subop | Historical | Required |
| startDate | {number millisecs since 1970-01-01} | Required |
| endDate | {number millisecs since 1970-01-01} | Required |
| vehicleIDs | {comma delimited list of vehicle ids } | Required |
| filter | {comma delimited list of event ids} | Required |
Query Response
{
"version":"0.6",
"reqId":"",
"status":"ok",
"sig":"-1187543771",
"dataset":{
"datasetname":"Report_HistoricalEx",
"tables":[
{
"cols":[
{
"id":"0",
"label":"Description",
"type":"string",
"p":{}
},
{
"id":"1",
"label":"Registration",
"type":"string",
"p":{}
},
{
"id":"2",
"label":"GPSDateTime",
"type":"datetime",
"p":{}
},
{
"id":"3",
"label":"Longitude",
"type":"number",
"p":{}
},
{
"id":"4",
"label":"Latitude",
"type":"number",
"p":{}
},
{
"id":"5",
"label":"EventID",
"type":"number",
"p":{}
},
{
"id":"6",
"label":"DistanceKm",
"type":"number",
"p":{}
},
{
"id":"7",
"label":"SpeedKph",
"type":"number",
"p":{}
},
{
"id":"8",
"label":"PlaceName",
"type":"string",
"p":{}
},
{
"id":"9",
"label":"Tag",
"type":"number",
"p":{}
},
{
"id":"10",
"label":"Parameter",
"type":"string",
"p":{}
},
{
"id":"11",
"label":"VehicleID",
"type":"number",
"p":{}
}
],
"rows":[...
Fields to Note:
- Description – vehicle description
- Registration – vehicle registration
- GPSDateTime – UTC GPS date time
- Longitude – GPS longitude
- Latitude – GPS latitude
- EventID – the vehicle event
- DistanceKm – distance in km to previous start/stop or moving only
- SpeedKph – GPS speed in kph
- PlaceName – Nearest client place (by centroid)
- Tag – Simple number payload (used for some event types)
- Parameter – JSON payload (used for some event types)
Time in Places
Provides a detailed information about what vehicles did within one or more place. Note that the information includes everything that happened from crossing the place boundary to leaving the boundary.
Query Parameters
| Parameter | Values | Notes |
| op | Report | Required |
| subop | TimeInPlaces | Required |
| startDate | {number in format YYYYMMDD} | Required |
| endDate | {number in format YYYYMMDD} | Required |
| locationIDs | {comma delimited list of location ids, or 0 for wildcard} | Required |
| locationGroupIDs | {comma delimited list of location group ids, or 0 for wildcard} | Required |
| daysOfWeek | {comma delimited list of days of week. 1 being Sunday} | Required |
Query Response
{
"version":"0.6",
"reqId":"",
"status":"ok",
"sig":"1675104936",
"dataset":{
"datasetname":"Report_TimeInPlaces",
"tables":[
{
"cols":[
{
"id":"0",
"label":"LocationGroupID",
"type":"number",
"p":{}
},
{
"id":"1",
"label":"LocationGroup",
"type":"string",
"p":{}
},
{
"id":"2",
"label":"LocationName",
"type":"string",
"p":{}
},
{
"id":"3",
"label":"LocationLng",
"type":"number",
"p":{}
},
{
"id":"4",
"label":"LocationLat",
"type":"number",
"p":{}
},
{
"id":"5",
"label":"Date",
"type":"datetime",
"p":{}
},
{
"id":"6",
"label":"VehicleID",
"type":"number",
"p":{}
},
{
"id":"7",
"label":"VehicleDesc",
"type":"string",
"p":{}
},
{
"id":"8",
"label":"VehicleReg",
"type":"string",
"p":{}
},
{
"id":"9",
"label":"Entry",
"type":"datetime",
"p":{}
},
{
"id":"10",
"label":"Exit",
"type":"datetime",
"p":{}
},
{
"id":"11",
"label":"DurationSecs",
"type":"number",
"p":{}
},
{
"id":"12",
"label":"MovingSecs",
"type":"number",
"p":{}
},
{
"id":"13",
"label":"IdlingSecs",
"type":"number",
"p":{}
},
{
"id":"14",
"label":"DistanceKm",
"type":"number",
"p":{}
},
{
"id":"15",
"label":"MaxSpeedKph",
"type":"number",
"p":{}
},
{
"id":"16",
"label":"SpeedingExceptions",
"type":"number",
"p":{}
},
{
"id":"17",
"label":"AvgSpeedKph",
"type":"number",
"p":{}
},
{
"id":"18",
"label":"Parameter",
"type":"string",
"p":{}
}
],
"rows":[Fields to note:
- LocationGroupID – location group id
- LocationGroup – location group
- LocationName – location name
- LocationLng – location centroid longitude
- LocationLat – location centroid latitude
- Date – start of day
- VehicleID – vehicle id
- VehicleDesc – vehicle description
- VehicleReg – vehicle registration
- Entry – entry date and time
- Exit – exit date and time
- DurationSecs – duration in location
- MovingSecs – moving time in location
- IdlingSecs – idling time in location
- DistanceKm – distance travelled within location
- MaxSpeedKph – max speed within location
- SpeedingExceptions – count of speeding exceptions
- AvgSpeedKph – avg speed within location
- Parameter – location parameter field containing json
Health
Gives a quick summary of all trackers. Includes information such as device type, last contact information and serial number.
Query Parameters
| Parameter | Values | Notes |
| op | Report | Required |
| subop | DeviceHealth | Required |
| groupIDs | {comma delimited list of vehicle group ids. Use 0 for wildcard} | Required |
Query Response
{
"version":"0.6",
"reqId":"",
"status":"ok",
"sig":"1843440100",
"dataset":{
"datasetname":"Report_Health",
"tables":[
{
"cols":[
{
"id":"0",
"label":"FolderID",
"type":"number",
"p":{}
},
{
"id":"1",
"label":"Folder",
"type":"string",
"p":{}
},
{
"id":"2",
"label":"VehicleID",
"type":"number",
"p":{}
},
{
"id":"3",
"label":"Registration",
"type":"string",
"p":{}
},
{
"id":"4",
"label":"Driver",
"type":"string",
"p":{}
},
{
"id":"5",
"label":"UnitTypeID",
"type":"number",
"p":{}
},
{
"id":"6",
"label":"UnitType",
"type":"string",
"p":{}
},
{
"id":"7",
"label":"UnitSerial",
"type":"string",
"p":{}
},
{
"id":"8",
"label":"LastEventID",
"type":"number",
"p":{}
},
{
"id":"9",
"label":"LastEvent",
"type":"string",
"p":{}
},
{
"id":"10",
"label":"LastSpeed",
"type":"number",
"p":{}
},
{
"id":"11",
"label":"LastLocationID",
"type":"string",
"p":{}
},
{
"id":"12",
"label":"LastContactUTC",
"type":"datetime",
"p":{}
},
{
"id":"13",
"label":"LastContactDays",
"type":"number",
"p":{}
},
{
"id":"14",
"label":"LastLongitude",
"type":"number",
"p":{}
},
{
"id":"15",
"label":"LastLatitude",
"type":"number",
"p":{}
},
{
"id":"16",
"label":"LastParameter",
"type":"string",
"p":{}
},
{
"id":"17",
"label":"Google",
"type":"string",
"p":{}
},
{
"id":"18",
"label":"UnitParameter",
"type":"string",
"p":{}
}
],
"rows":[Fields to note:
- FolderID – vehicle folder id
- FolderName – vehicle folder name
- Registration – vehicle registration
- Driver – assigned driver name
- UnitTypeID – internal device type id
- UnitType – device type
- UnitSerial – device serial number
- LastEventID – last event type
- LastEvent – description of last event
- LastLocationID – last contact user location
- LastContactUTC – last device contact
- LastContactDays – number of days since last contact
- LastLatitude – last device latitude
- LastLongitude – last device longitude
- LastParameter – last device ‘payload’, extra data that may be returned by device with positional data
- Google – google link to last position
- UnitParameter – last device counters. Specific to particular device. Empty for most devices.
Back to: Contents
