Telematics Data Input Specification

Overview

This document outlines the minimum and preferred data inputs required to integrate a telematics data source with Nuonic.

Nuonic uses four datsets to perform its calculations:

Vehicle Register (core)
GPS Positions (core)
Trip Summary (optional, highly recommended)
Event Records (optional)

As a general rule, the more complete your dataset is, the more accurate Nuonic analysis will be.

Vehicle Register

The Vehicle Register is a list of all tracked devices/assets for a client, with as much vehicle specification data as possible.

Required fields

Field	Description	Type
`client_vehicle_id`	Unique ID of the telematics device installed in the vehicle	`STRING`
`device_type`	Device model installed in the vehicle	`STRING`
`registration`	Registration plate number	`STRING`
`make`	Manufacturer	`STRING`
`model`	Model name	`STRING`
`category`	Nuonic vehicle category	`STRING`
`ftc_on_road`	Indicates heavy (`GVM > 4.5t`) vs light vehicle	`BOOLEAN`

Optional fields

Field	Description	Type
`vin`	Vehicle serial/identifier number	`STRING`
`registration_state`	State or region where the vehicle is registered	`STRING`
`fuel_type`	Vehicle fuel type	`STRING`
`engine_displacement`	Engine size (for ICE vehicles)	`DECIMAL`
`engine_cylinders`	Number of engine cylinders (for ICE vehicles)	`INTEGER`
`transmission`	Vehicle transmission type	`STRING`
`description`	Free-text vehicle description	`STRING`
`business_division`	Business unit/cost centre assignment	`STRING`
`acquired_date`	Asset acquisition date	`DATE`
`disposed_date`	Asset disposal date	`DATE`
`registration_charge_code`	Regulatory class/code (for example NHVR class)	`STRING`
`registration_date`	Last registration date	`DATE`
`registration_cost`	Registration cost	`MONEY`
`model_year`	Vehicle model year	`INTEGER`
`gross_vehicle_mass`	Gross vehicle mass in kilograms	`DECIMAL`
`gross_combined_mass`	Maximum registered combination mass in kilograms	`DECIMAL`
`axle_count`	Number of axles	`INTEGER`
`fuel_burn_rate_driving`	Average fuel burn while driving (`L/100km`)	`DECIMAL`
`fuel_burn_rate_idle`	Average fuel burn while idling (`L/hour`)	`DECIMAL`
`auxiliary_equipment`	Auxiliary equipment type enabled on vehicle	`STRING`
`auxiliary_fuel_use`	Auxiliary fuel-use category	`STRING`
`auxiliary_fuel_percentage`	Percentage of fuel attributed to auxiliary use	`INTEGER`
`fuel_burn_rate_auxiliary`	Average fuel burn during auxiliary operation (`L/hour`)	`DECIMAL`

Trip Summary (optional, recommended)

Trip Summary is the set of trip start/end positions and timestamps as defined by the telematics system.

This dataset is optional, but strongly recommended because it improves alignment between source telematics outputs and Nuonic calculations.

Required fields

Field	Description	Type
`device_id`	Unique ID of the telematics device installed in the vehicle	`STRING`
`start_timestamp`	Trip start timestamp	`TIMESTAMP`
`end_timestamp`	Trip end timestamp	`TIMESTAMP`
`start_latitude`	Latitude at trip start	`GPS COORDINATE (3,6)`
`start_longitude`	Longitude at trip start	`GPS COORDINATE (3,6)`
`end_latitude`	Latitude at trip end	`GPS COORDINATE (3,6)`
`end_longitude`	Longitude at trip end	`GPS COORDINATE (3,6)`

Optional fields

Field	Description	Type
`trip_id`	Provider trip identifier	`STRING`
`next_trip_timestamp`	Timestamp of the next trip start after current trip ends	`TIMESTAMP`
`start_odometer`	Odometer at trip start (`km`)	`DECIMAL`
`end_odometer`	Odometer at trip end (`km`)	`DECIMAL`
`total_distance`	Trip distance (`km`)	`DECIMAL`
`total_time`	Total trip duration (`seconds`)	`DECIMAL`
`driving_time`	Driving duration (`seconds`)	`DECIMAL`
`idle_time`	Idling duration (`seconds`)	`DECIMAL`
`auxiliary_time`	Auxiliary equipment duration (`seconds`)	`DECIMAL`
`total_fuel_consumed`	Total fuel consumed during trip (`litres`)	`DECIMAL`
`driving_fuel_consumed`	Fuel consumed while driving (`litres`)	`DECIMAL`
`idle_fuel_consumed`	Fuel consumed while idling (`litres`)	`DECIMAL`
`average_fuel_economy`	Average fuel economy over trip (`L/100km`)	`DECIMAL`
`driving_fuel_economy`	Average fuel economy while driving (`L/100km`)	`DECIMAL`
`idle_fuel_economy`	Average fuel economy while idling (`L/hour`)	`DECIMAL`
`auxiliary_fuel_economy`	Average fuel economy during auxiliary operation (`L/hour`)	`DECIMAL`

GPS Positions

GPS Positions is the complete set of position points and related state captured by the telematics device.

Vehicle activity state (engine running/off) is a critical input. This can be supplied explicitly through ignition_on, or defined as a dataset-level rule when all points are only captured while ignition is on.

Required fields

Field	Description	Type
`device_id`	Unique ID of the telematics device installed in the vehicle	`STRING`
`timestamp`	Position timestamp	`TIMESTAMP`
`latitude`	Latitude at position	`GPS COORDINATE (3,6)`
`longitude`	Longitude at position	`GPS COORDINATE (3,6)`

Optional fields

Field	Description	Type
`trip_id`	Trip identifier this point belongs to	`STRING`
`driver_id`	Driver identifier at time of reading	`STRING`
`satellites`	Number of satellites used for GPS fix	`INTEGER`
`hdop`	Horizontal dilution of precision	`DECIMAL`
`vdop`	Vertical dilution of precision	`DECIMAL`
`ignition_on`	Engine/ignition state	`BOOLEAN`
`auxiliary_on`	Auxiliary equipment state	`BOOLEAN`
`odometer`	Odometer reading at timestamp (`km`)	`DECIMAL`
`fuel`	Fuel level reading at timestamp (`litres`)	`DECIMAL`
`event`	Provider event code/name captured at timestamp	`STRING`
`speed`	Vehicle speed at timestamp (`km/hour`)	`DECIMAL`
`altitude`	Altitude at timestamp (metres above sea level)	`DECIMAL`
`heading`	Vehicle heading at timestamp (degrees)	`DECIMAL`

Event Records

Event Records are timestamped operational events (for example, PTO on/off) that can be aligned with trip and position datasets.

Required fields

Field	Description	Type
`device_id`	Unique ID of the telematics device/asset generating the event	`STRING`
`timestamp`	Timestamp when the event occurred	`TIMESTAMP`
`event_identifier`	Event identifier or event name (for example `pto`)	`STRING`
`event_value`	Event state/value (for example `on/off` or `0/1`)	`STRING`

Accepted list values

Vehicle category values

B-TRIPLE TRUCK
BACKHOE LOADER
COMBINE HARVESTER
DUMP TRUCK
FERTILISER SPREADER
FORKLIFT
FRONT END LOADER
GARBAGE TRUCK
GRADER
LARGE BUS
LARGE UTILITY
LARGE VAN
MOWER
NO FUEL USE
PRIME MOVER TRUCK
QUAD BIKE
RIGID TRUCK
ROAD CONSTRUCTION
SPECIALISED
TRACTOR
WHEELED BULLDOZER
WHEELED EXCAVATOR

Fuel type values

Diesel
Liquid Petroleum Gas
Other
Unleaded Petrol

Transmission values

Automatic
CVT
Dual Clutch
Electric
Manual

Auxiliary fuel use values

AIR CONDITIONING
CONCRETE MIXING
NONE
REFRIGIRATION
SLEEPER CABIN
SPECIALISED EQUIPMENT
WASTE COLLECTION