fbpx

Vehicle

Groups
March 4, 2018
Event Types
March 5, 2018

Vehicle information is generally returned in a VehicleDetailsDataSet Asset table.

To reduce the number of server calls this is an unnormalised view of the current state of the vehicle. It includes information such as the currently assigned driver and tracker as well as some standard vehicle fields.

For calls that result in positions, data is returned in a VehiclePositionDataSet.

Note that the unique VehicleId field is important as a number of other calls in the system require this as a parameter.

Calls in this section


GetAllVehiclesFilteredByUserID

Retrieve all vehicles for the current user. Omits all Vehicles in folders for which the user does not have permissions.

Request (Query Parameters)
ParameterValueNotes
opVehicleRequired
subopGetAllVehiclesFilteredByUserIDRequired

*Optional Parameters

Response

The dataset returned is a VehicleDetailsDataSet. This dataset is returned by a number of other Vehicle calls. This is a wide dataset containing large amount of data related to a vehicle.

{
   "version":"0.6",
   "reqId":"",
   "status":"ok",
   "sig":"388421001",
   "dataset":{
      "datasetname":"VehicleDetailsDataSet",
      "tables":[
         {
            "cols":[
               {
                  "id":"0",
                  "label":"VehicleID",
                  "type":"number",
                  "p":{
                     "autoincrement":true
                  }
               },
               {
                  "id":"1",
                  "label":"CurrentUnitID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"2",
                  "label":"TypeID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"3",
                  "label":"GroupID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"4",
                  "label":"Description",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"5",
                  "label":"Registration",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"6",
                  "label":"HourlyCost",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"7",
                  "label":"KMCost",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"8",
                  "label":"DepotID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"9",
                  "label":"DepotName",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"10",
                  "label":"TimeStamp",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"11",
                  "label":"DriverID",
                  "type":"number",
                  "p":{
                     "autoincrement":true
                  }
               },
               {
                  "id":"12",
                  "label":"Name",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"13",
                  "label":"DriverStartDate",
                  "type":"datetime",
                  "p":{}
               },
               {
                  "id":"14",
                  "label":"DriverEndDate",
                  "type":"datetime",
                  "p":{}
               },
               {
                  "id":"15",
                  "label":"UnitStartDate",
                  "type":"datetime",
                  "p":{}
               },
               {
                  "id":"16",
                  "label":"UnitEndDate",
                  "type":"datetime",
                  "p":{}
               },
               {
                  "id":"17",
                  "label":"CurrentDisplayTerminalID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"18",
                  "label":"CurrentDisplayTerminalDescription",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"19",
                  "label":"Make",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"20",
                  "label":"Model",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"21",
                  "label":"CurrentOdo",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"22",
                  "label":"CurrentHoursWorked",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"23",
                  "label":"EmsEngineType",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"24",
                  "label":"FreeText",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"25",
                  "label":"EmissionFactorType",
                  "type":"number",
                  "p":{}
               }
            ],
            "rows":[
               
            ],
            "p":{
               "tablename":"Assets",
               "primarykey":[
                  0
               ]
            }
         }
      ]
   }
}

Fields to note include:

  • vVehicleId – unique internal id of the vehicle
  • vTypeId – vehicle type id
  • vCurrentUnitID – currently assigned tracker id (this is *not* the tracker serial number)
  • uvaStartDate – vCurrentUnitID assignment start in UTC
  • uvaEndDate – vCurrentUnitID assignment end in UTC
  • vGroupID – the vehicle group
  • vRegistration – the vehicle registration
  • vDescription – the description
  • vMake – the vehicle make
  • vModel – the vehicle model
  • vFreeText – free text, as displayed in notes field
  • dDriverId – currently assigned driver (internal id)
  • dDriverName – currently assigned driver name
  • vCurrentOdo – kms travelled
  • vCurrentHoursWorked – hours worked

GetVehicleByGroupID

Retrieve all vehicles that are contained in the provided group. Note that subgroup contents are not returned.

Request (Query Parameters)
ParameterValueNotes
opVehicleRequired
subopGetVehicleByGroupIDListRequired
groupID{comma delimited list of groupids}Required. Note that recursive subgroups are not returned.

*Optional Parameters

Response

See VehicleDetailsDataSet


GetVehicleByGroupIDList

Retrieve all vehicles that are contained in any of the provided groups. Note that subgroup contents are not returned.

Request (Query Parameters)
ParameterValueNotes
opVehicleRequired
subopGetVehicleByGroupIDListRequired
groupIDs{comma delimited list of groupids}Required. Note that recursive subgroups are not returned.

*Optional Parameters

Response

See VehicleDetailsDataSet


GetLastKnownVehiclePositions

This call retrieves the last known vehicle position for one or more vehicles. The call will only return the most recent start, stop, moving or heartbeat position. It does not return other event types.

Request (Query Parameters)
ParameterValueNotes
opVehicleRequired
subopGetLastKnownVehiclePositionsRequired
vehicleIds{comma delimited list of vehicleids}Required

*Optional Parameters

Response

Note that the return from this call is not a VehicleDetailsDataSet but a VehiclePositionDataset. This dataset contains 2 tables. The first table is a list of last known start, stop, moving or heartbeat positions for each vehicle. The second table is the current server time. All datetimes in returned data are in UTC. The server time is returned as client datetimes cannot always be relied on.

As the dataset contains datetimes, see this note about datetimes from the server.

{
   "version":"0.6",
   "reqId":"",
   "status":"ok",
   "sig":"-1104426066",
   "dataset":{
      "datasetname":"VehiclePositionDataset",
      "tables":[
         {
            "cols":[
               {
                  "id":"0",
                  "label":"PosID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"1",
                  "label":"UnitID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"2",
                  "label":"GPSDateTime",
                  "type":"datetime",
                  "p":{}
               },
               {
                  "id":"3",
                  "label":"EventID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"4",
                  "label":"Longitude",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"5",
                  "label":"Latitude",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"6",
                  "label":"Distance",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"7",
                  "label":"Bearing",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"8",
                  "label":"Speed",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"9",
                  "label":"Height",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"10",
                  "label":"NumSats",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"11",
                  "label":"Validity",
                  "type":"boolean",
                  "p":{}
               },
               {
                  "id":"12",
                  "label":"DGPS",
                  "type":"boolean",
                  "p":{}
               },
               {
                  "id":"13",
                  "label":"VehicleID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"14",
                  "label":"DriverID",
                  "type":"number",
                  "p":{}
               },
               {
                  "id":"15",
                  "label":"DriverName",
                  "type":"string",
                  "p":{}
               },
               {
                  "id":"16",
                  "label":"Parameter",
                  "type":"string",
                  "p":{}
               }
            ],
            "rows":[
               
            ],
            "p":{
               "tablename":"Positions",
               "primarykey":[
                  0
               ]
            }
         },
         {
            "cols":[
               {
                  "id":"0",
                  "label":"CurrentUTC",
                  "type":"datetime",
                  "p":{}
               }
            ],
            "rows":[
               {
                  "c":[
                     {
                        "v":new Date(1614936565690)
                     }
                  ],
                  "p":{
                     "rowstate":"unchanged"
                  }
               }
            ],
            "p":{
               "tablename":"UTCTime",
               "primarykey":[]
            }
         }
      ]
   }
}

Fields to note include:

  • PosID – internal unique record id
  • UnitID – assigned tracker id (this is *not* the tracker serial number)
  • GPSDateTime – gps UTC datetime
  • EventID – the event (start,stop,moving or heartbeat)
  • Longitude – gps longitude
  • Latitude – gps latitude
  • Distance – distance to previous record in km
  • Bearing – current bearing
  • Speed – current speed in km/h
  • Height – height, quality depends on tracker type
  • NumSats – numsats, quality depends on tracker type
  • Validity – ignore
  • DGPS – ignore
  • VehicleID – vehicleid
  • DriverID – assigned driver id
  • DriverName – assigned driver name
  • Parameter – JSON payload containing other payload

GetVehiclePositionsLatest

This call retrieves the most recent 20 last known vehicle positions for one or more vehicles. The call will only return the most recent starts, stops, moving or heartbeat position.

This call is most useful for a single vehicle, as a track can be drawn up to the current position.

Request (Query Parameters)
ParameterValueNotes
opVehicleRequired
subopGetVehiclePositionsLatestRequired
vehicleIds{comma delimited list of vehicleids}Required

*Optional Parameters

Response

Note that the return from this call is not a VehicleDetailsDataSet but a VehiclePositionDataset. This dataset contains 2 tables. The first table is a list of last known start, stop, moving or heartbeat positions for each vehicle. The second table is the current server time. All datetimes in returned data are in UTC. The server time is returned as client datetimes cannot always be relied on.

As the dataset contains datetimes, see this note about datetimes from the server.

See VehiclePositionDataset

Back to: Contents