fbpx

Reports

Basic Concepts
January 8, 2018
Data Concepts
March 2, 2018

This 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
ParameterValuesNotes
opReportRequired
subopDetailedRequired
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

*Optional Parameters

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
ParameterValuesNotes
opReportRequired
subopHistoricalRequired
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

*Optional Parameters

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
ParameterValuesNotes
opReportRequired
subopTimeInPlacesRequired
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

*Optional Parameters

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
ParameterValuesNotes
opReportRequired
subopDeviceHealthRequired
groupIDs{comma delimited list of vehicle group ids. Use 0 for wildcard}Required

*Optional Parameters

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