Telematics Event Specification

Use this schema when sending telematics events to Cartrack.

Important notes

• Time must be in UTC, ISO-8601 format
• Enforce event uniqueness (e.g., via provider_event_id)
• Validate that event_ts <= ingested_at + tolerance (ingestion time is server-side)
• Version the schema or route to support future changes
• Odometer unit is kilometers

Example payload

{
  "event_type": "PERIODIC",
  "event_ts": "2026-01-19T08:42:15Z",

  "chassis_number": "ABC12345678901234",

  "source": {
    "provider": "third_party_x",
    "device_id": "IMEI123456789",
    "provider_event_id": "evt-984739287",
    "provider_received_ts": "2026-01-19T08:42:18Z"
  },

  "position": {
    "latitude": 1.3521,
    "longitude": 103.8198,
    "altitude": 15
  },

  "telemetry": {
    "speed": 54,
    "ignition": true,
    "rpm": 2200,
    "odometer": 45231.4
  }
}

Field definitions

Top-level fields

Field	Type	Required	Notes
event_type	string	yes	IGNITION_ON, IGNITION_OFF, PERIODIC
event_ts	ISO-8601 UTC	yes	Time when event occurred on device
chassis_number	string	yes	Vehicle Identification Number (VIN), exactly 17 characters
source	object	yes	Identifies the event origin
position	object	conditional	Required for location events
telemetry	object	optional	Vehicle signals

source

Field	Type	Required	Notes
provider	string	yes	Logical source name
device_id	string	optional	IMEI, serial, etc.
provider_event_id	string	recommended	Used for idempotency
provider_received_ts	ISO-8601 UTC	optional	When provider received the event

position

Field	Type	Required	Notes
latitude	number	yes	Decimal degrees
longitude	number	yes	Decimal degrees
altitude	number	optional	Meters above sea level

telemetry

Field	Type	Required	Units / Notes
speed	number	yes	km/h
ignition	boolean	yes	true = ON
rpm	number	optional	Revolutions per minute
odometer	number	yes	Kilometers

Event-type expectations

Event type	Position	Telemetry
IGNITION_ON	required	Marks the beginning of a trip
IGNITION_OFF	required	Marks the end of a trip
PERIODIC	required	Recommended. Used to plot the path taken by the vehicle