Data Structuring

What do the Verilocation models represent

The following page endeavours to explain the rational behind our data models and suggestions for interacting with our v1API returned data.

Asset Data

Verilocation API allows an account assets to be managed via the endpoints. Account assets that are commonly interacted with are:

`Vehicle`

For many accounts, Vehicle models represent the 'Driving' assets that a company has within their fleet. They can also be used to hold representations of other assets with tracking devices e.g. HGV Trailer units.

All .../public/v1/vehicles/... endpoints return Vehicle data with the majority requiring a VehicleId and returning data models specific to devices registered to that Vehicle.

Vehicle Model
[
  {
    "id": 0,
    "reg": "string",
    "make": "string",
    "model": "string",
    "shortReg": "string",
    "vehicleType": 0                          // enum as int - see below
  }
]

enum vehicleType
{
    Trailer = 0,
    Car = 1,
    BusOrPSV = 5,
    HgvLessThan12T = 6,
    Hgv12Tto22T = 7,
    HgvGreaterThan22T = 8,
    Lcv = 9,
    Motorcycle = 10,
    Unknown = 11,
    Asset = 12,
    Plant = 13
}

A list of all Vehicle models available on an account can be recalled from

.../public/v1/vehicles

`Geofence`

A Geofence model represents an enclosed area of land which can be expressed using a central point and a radius or a series of lat/lng points that define the edge of the Geofence

Geofence models can be Created, Recalled Updated and Deleted via API

Geofence Model
[
  {
    "addr1": "string",
    "addr2": "string",
    "addr3": "string",
    "addr4": "string",
    "description": "string",
    "descriptionExt": "string",
    "email": "string",
    "geofenceType": 0,                       // enum as int - see below
    "id": 0,
    "latitude": 0,
    "longitude": 0,
    "radius": 0,
    "points": [
      [
        0
      ]
    ],
    "tags": [
      0
    ]
  }
]

enum geofenceType
{
    Polygon = 0,
    Circle = 1
}

Geofence models can be requested via the

.../public/v1/geofences/...

endpoints, and return Geofence model

Driver

Driver models represent human Drivers that have been registered with Verilocation for an account.

The Verilocation API suite has functionality to Create, Update and Recall Driver models.

The .../public/v1/drivers controller also holds endpoints for manually assigning and unassigning a Driver to a Vehicle model as well as recalling all current VehicleDriverMapping records

Driver Model
[
  {
    "id": 0,
    "name": "string",
    "mobile": "string",
    "status": 0,                            // enum as int - see below
    "username": "string",
    "password": "string",
    "email": "string",
    "buttonId": "string"                    // Tacho card Id number
  }
]

enum status
{
    InActive = 0,
    Active = 1
}

Driver data can be recalled from

.../public/v1/drivers

endpoint and return a Driver model

Aggregated Data

Within the Verilocation system, for a large portion of data, we use aggregated models.

Aggregated models are created while ingressing Plot data. They are triggered (opened/closed) by the contents of a Plot e.g. the Plot's ReasonCode, and while open, will be fed all relevant data from each processed Plot.

This provides models which in many cases, makes accessing and processing the individual Plot lists as redundant and is far faster to request than calls to Plot endpoints.

`Journey`

A Journey is an aggregated data model which holds the accumulated data from all Plot points received from the Journey start time until the Journey end time.

A Journey is created while ingesting Plot data into the system and are triggered by a Plot such as 'Ignition on' whether from the Tracker (GPS) or FMS (CAN).

A Journey is ended by a Plot such as 'Ignition off', again from GPS or CAN.

While a Journey is building (between start and end), each Plot that enters the system for the device has the contained data added to the Journey model.

A Journey is a universal concept for Verilocation and has no dependencies in itself on GPS or CAN Plot points. If a Journey is created using only GPS data then only GPS fields will be populated and, due to serialisation settings, will not be included on the returned models.

Journey Vs JourneyRecord

The v1API endpoints have two public models for Journey data.

Journey data obtained through the

.../public/v1/vehicles/...

endpoints, are a shortened model containing basic Journey information only, such as start/end time, locations, distance etc

Journey Model
[
    {
    "id": 0,
    "vehicleId": 0,
    "startLocation": "string",
    "endLocation": "string",
    "startLatitude": 0,
    "startLongitude": 0,
    "endLatitude": 0,
    "endLongitude": 0,
    "distance": 0,
    "averageSpeed": 0,
    "cost": 0,
    "comment": "string",
    "startUtc": "2023-02-27T11:16:50.572Z",
    "endUtc": "2023-02-27T11:16:50.572Z",
    "isBusiness": true
  }
]

JourneyRecord data obtained through the

.../public/v1/journeys/...

endpoints, are an extended model with event information, odometer readings, fuel data etc

JourneyRecord Model
[
    {
    "id": 0,
    "vehicleId": 0,
    "driverId": 0,
    "startLocation": "string",
    "endLocation": "string",
    "startLatitude": 0,
    "startLongitude": 0,
    "endLatitude": 0,
    "endLongitude": 0,
    "startUtc": "2023-02-27T11:16:50.555Z",
    "endUtc": "2023-02-27T11:16:50.555Z",
    "startPlotId": 0,
    "endPlotId": 0,
    "expensed": true,
    "isPersonal": true,
    "journeyType": 0,
    "endCompositeLocationId": 0,
    "startCompositeLocationId": 0,
    "comment": "string",
    "cost": 0,
    "averageSpeed": 0,
    "distance": 0,
    "distanceKm": 0,
    "odometerKmStart": 0,
    "odometerKmEnd": 0,
    "maxSpeedKph": 0,
    "distanceKmCan": 0,
    "fuelLevelStart": 0,
    "fuelLevelEnd": 0,
    "odometerKmCanStart": 0,
    "odometerKmCanEnd": 0,
    "accelerationCountGps": 0,
    "brakeApplications": 0,
    "brakeApplicationsOverThreshold": 0,
    "brakeDistance": 0,
    "badAnticipationCount": 0,
    "coastingDuration": 0,
    "coastingDistance": 0,
    "cruiseDuration": 0,
    "corneringCountGps": 0,
    "decelerationCountGps": 0,
    "drivingDuration": 0,
    "engineOnDuration": 0,
    "fuelUsedDriving": 0,
    "fuelUsedIdle": 0,
    "fuelUsedPto": 0,
    "fuelUsedTotal": 0,
    "ptoDuration": 0,
    "overRevDuration": 0,
    "overSpeedDuration": 0,
    "overTorqueDuration": 0,
    "idlingDuration": 0,
    "overIdlingDuration": 0,
    "overIdlingCount": 0,
    "totalWeight": 0,
    "isBusiness": true
  }
]

`GeofenceVisit`

A GeofenceVisit represent the time that a Vehicle or Trailer spent within the boundaries of a geofenced area.

A GeofenceVisit is created when ingressing a Plot where the Lat/Lngs, compared to last Plot Lat/Lngs, cross a Geofenced boundary to reside inside the fenced area.

A GeofenceVisit is closed when a Plot containing Lat/Lngs re-crosses the Geofenced boundary to be outside the area again

GeofenceVisit Model
[
  {
    "id": 0,
    "geofenceId": 0,
    "vehicleId": 0,
    "startPlotId": 0,
    "endPlotId": 0,
    "startUtc": "2023-02-27T11:45:30.198Z",
    "endUtc": "2023-02-27T11:45:30.198Z"
  }
]

GeofenceVisit data can be requested via the

.../public/v1/geofenceVisits/...

endpoints, and return GeofenceVisit models

`TemperatureAlarm`

A TemperatureAlarm model, represents a period if time when an individual Probe or collection of Probe (zone) was reporting temperatures that fall outside the range of the Profile bounds applied to the Probe

TemperatureAlarm Model
[
  {
    "id": 0,
    "temperatureProbeId": 0,
    "position": 0,
    "vehicleId": 0,
    "timestamp": "2023-03-31T09:28:20.238Z",
    "source": 0,                             // enum as int - see below
    "plotId": 0,
    "temperature": 0,
    "state": 0,                              // enum as int - see below
    "upperBound": 0,
    "lowerBound": 0
  }
]

enum source
{
    Tracker = 0,
    Transcan = 1,
    SecureSeal = 2,
    IBox = 3,
    Carrier = 4
}

enum state
{
    InActive = 0,
    Active = 1
}

TemperatureAlarm data can be requested via the

.../public/v1/temperature/alarms/...

endpoints, and return TemperatureAlarm models

PreviousWelcome to Verilocation V1 API NextAuthentication

Last updated 2 years ago