Skip to main content

Data Input Specification

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

There are three primary data sets and one secondary data set that Prism may use, each with required and optional elements. As a general rule, the more elements that can be provided to Prism, the more accurate the analysis results will be.

Vehicle Register

The Vehicle Register is a list of all devices tracked for a client by the telematics system, with as much vehicle specification data as possible.

Field name

Description

Data Type

Required / Optional

device_id

Unique ID of the telematics device installed in the vehicle

STRING

REQUIRED

device_type

Device model installed in the vehicle

STRING

REQUIRED

vin

The unique serial number of the vehicle’s engine

STRING

OPTIONAL

registration

Registration plate number

STRING

REQUIRED

registration_state

State the vehicle is registered in

STRING

OPTIONAL

make

Manufacturer

STRING

REQUIRED

model

Model name

STRING

REQUIRED

class

NHVR Vehicle Class

STRING

OPTIONAL

category

Prism Vehicle Category (see list on this page)

STRING

REQUIRED

fuel_type

Fuel type (see list on this page)

STRING

OPTIONAL

engine_displacement

Engine size in Litres for ICE vehicles

DECIMAL

OPTIONAL

engine_cylinders

Number of cylinders for ICE vehicles

INTEGER

OPTIONAL

transmission

Transmission type (see list on this page)

STRING

OPTIONAL

description

Descriptive text

STRING

OPTIONAL

business_division

Business unit the vehicle is allocated to

STRING

OPTIONAL

acquired_date

Date of acquisition

DATE

OPTIONAL

disposed_date

Date of disposal

DATE

OPTIONAL

registration_date

Date of last registration

DATE

OPTIONAL

registration_cost

Amount paid for last registration

MONEY

OPTIONAL

model_year

Model year

INTEGER

OPTIONAL

gross_vehicle_mass

In Kilograms

DECIMAL

OPTIONAL

gross_combined_mass

Maximum registered combination mass In Kilograms

DECIMAL

OPTIONAL

axle_count

Maximum number of axles

INTEGER

OPTIONAL

auxiliary_equipment

Auxiliary equipment enabled on the vehicle (from list on this page)

STRING

OPTIONAL

fuel_burn_rate_driving

Average fuel burn rate while driving in Litres per 100KM

DECIMAL

OPTIONAL

fuel_burn_rate_idle

Average fuel burn rate while idling in Litres per Hour

DECIMAL

OPTIONAL

fuel_burn_rate_auxiliary

Average fuel burn rate while operating auxiliary equipment in Litres per Hour

DECIMAL

OPTIONAL

Trip Summary

This is the set of trip start and end positions and time stamps, as defined by the telematics system.

This data set is optional but is highly recommended as it enables Prism results to be significantly less conservative and ensure maximum alignment between data viewed in the telematics system and in Prism.

If this data cannot be provided, Prism uses algorithms to estimate trip start and end points which generally reduce the amount of valid idling time that is included.

Field name

Description

Data Type

Required / Optional

device_id

Unique ID of the telematics device installed in the vehicle

STRING

REQUIRED

trip_id

Unique ID of the trip assigned by the telematics system

STRING

OPTIONAL

start_timestamp

Timestamp of the trip start

TIMESTAMP

REQUIRED

end_timestamp

Timestamp of the trip end

TIMESTAMP

REQUIRED

next_trip_timestamp

Timestamp of the start of the next trip (after engine off period following trip end)

TIMESTAMP

OPTIONAL

start_latitude

Latitude position at trip start

GPS COORDINATE (3, 6)

REQUIRED

start_longitude

Longitude position at trip start

GPS COORDINATE (3, 6)

REQUIRED

end_latitude

Latitude position at trip end

GPS COORDINATE (3, 6)

REQUIRED

end_longitude

Longitude position at trip end

GPS COORDINATE (3, 6)

REQUIRED

start_odometer

Odometer reading, in KM, at trip start

DECIMAL

OPTIONAL

end_odometer

Odometer reading, in KM, at trip end

DECIMAL

OPTIONAL

total_distance

Distance of complete trip, in KM

DECIMAL

OPTIONAL

total_time

Duration of trip, in Seconds

DECIMAL

OPTIONAL

driving_time

Duration of driving sections of trip, in Seconds

DECIMAL

OPTIONAL

idle_time

Duration of idle sections of trip, in Seconds

DECIMAL

OPTIONAL

auxiliary_time

Duration of auxiliary equipment operation during trip, in Seconds

DECIMAL

OPTIONAL

total_fuel_consumed

Fuel consumed during complete trip, in Litres

DECIMAL

OPTIONAL

driving_fuel_consumed

Fuel consumed during driving sections of trip, in Litres

DECIMAL

OPTIONAL

idle_fuel_consumed

Fuel consumed during during idle sections of trip, in Litres

DECIMAL

OPTIONAL

average_fuel_economy

Average fuel consumption for the trip, in Litres per 100KM

DECIMAL

OPTIONAL

driving_fuel_economy

Average fuel consumption for the driving sections of the trip, in Litres per 100KM

DECIMAL

OPTIONAL

idle_fuel_economy

Average fuel consumption for the idle sections of the trip, in Litres per Hour

DECIMAL

OPTIONAL

auxiliary_fuel_economy

Average fuel consumption for the auxiliary equipment operation sections of the trip, in Litres per Hour

DECIMAL

OPTIONAL

GPS Positions

This data set is the entire list of GPS positions and state captured by the telematics device that form the Trips.

Vehicle Activity State ( whether the engine is running or not) is a critical element of this data set. This may be provided either as a field in the data set (‘ignition_on’ in optional fields) or as a rule that applies to the entire data set.

Some telematics systems only capture data while the engine is running, switching the engine on activates the tracking system. In that case we do not need the ‘ignition_on’ field because we can safely assume that the engine was running at all position readings, but this must be explicitly communicated by the telematics provider.

Field name

Description

Data Type

Required / Optional

device_id

Unique ID of the telematics device installed in the vehicle

STRING

REQUIRED

trip_id

Unique ID of the Trip this position reading belongs to

STRING

OPTIONAL

driver_id

Unique ID of the vehicle driver at the time of position reading

STRING

OPTIONAL

timestamp

Time at position reading

TIMESTAMP

REQUIRED

latitude

Longitude of position

GPS COORDINATE (3, 6)

REQUIRED

longitude

Latitude of position

GPS COORDINATE (3, 6)

REQUIRED

satellites

Number of satellites used to obtain the GPS position fix

INTEGER

OPTIONAL

hdop

Horizontal dilution of precision

DECIMAL

OPTIONAL

vdop

Vertical dilution of precision

DECIMAL

OPTIONAL

ignition_on

Indicator of ignition being on or off (engine is running for ICE vehicles)

BOOLEAN

OPTIONAL

auxiliary_on

Indicator of auxiliary equipment being in operation or not at time of reading

BOOLEAN

OPTIONAL

odometer

Odometer reading at time of position in KM

DECIMAL

OPTIONAL

fuel

Fuel level reading at time of position in Litres

DECIMAL

OPTIONAL

event

Any system, vehicle or device event occurring at the time of position reading

STRING

OPTIONAL

speed

Vehicle speed at time of position reading in KM per Hour

DECIMAL

OPTIONAL

altitude

Altitude speed at time of position reading in Metres above sea level

DECIMAL

OPTIONAL

heading

Heading speed at time of position reading in Degrees

DECIMAL

OPTIONAL

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.