Telemetry Schema Reference

The Axle Engine accepts vehicle telemetry data in a flexible format. This document covers the standard schema and auto-mapping features.

Quick Reference

Key Takeaway

Only vehicleId is required. The more fields you provide, the better the predictions.

Required Fields

Field	Type	Description	Example
vehicleId	string	Required - Unique vehicle identifier	"TRUCK-001", "VIN123ABC"

---

Recommended Fields

These 5 fields significantly improve prediction accuracy:

Field	Type	Unit	Range	Description
engine_speed	number	RPM	0-10,000	Engine revolutions per minute
coolant	number	°C	-40 to 150	Engine coolant temperature
battery_voltage	number	V	0-30	Battery voltage
fuel_level	number	%	0-100	Fuel level percentage
vehicleSpeed	number	km/h	0-300	Vehicle speed

---

All Supported Fields

Engine Metrics

Field	Type	Unit	Description
engine_speed	number	RPM	Engine RPM
coolant	number	°C	Coolant temperature
engineOilTemp	number	°C	Oil temperature
engineFuelTemp	number	°C	Fuel temperature

Vehicle Metrics

Field	Type	Unit	Description
vehicleSpeed	number	km/h	Vehicle speed
obdDistance	number	km	Odometer reading
runTime	number	seconds	Engine runtime
current_gear	integer	-	Current gear

Electrical

Field	Type	Unit	Description
battery_voltage	number	V	Battery voltage

Fuel

Field	Type	Unit	Description
fuel_level	number	%	Fuel level
fuel_consumption	number	L/100km	Fuel consumption rate

Environment

Field	Type	Unit	Description
ambient_air_temperature	number	°C	Outside temperature

Warning Lamps

Field	Type	Values	Description
mil_lamp	string	"LAMP_ON", "LAMP_OFF"	Check Engine light
protect_lamp	string	Same as above	Engine protection warning
amber_warning_lamp	string	Same as above	Amber warning
red_stop_lamp	string	Same as above	Red stop warning

Diagnostics

Field	Type	Description	Example
dtc_codes	array	Active DTC fault codes	["P0301", "P0420"]

GPS (Optional)

Field	Type	Range	Description
latitude	number	-90 to 90	GPS latitude
longitude	number	-180 to 180	GPS longitude

---

Auto-Mapping (Legacy Support)

The Axle Engine automatically maps common alternative field names to the standard schema. This enables zero-config integration with legacy telematics systems.

How It Works

1. Send data with your existing field names
2. Axle Engine auto-detects and maps them
3. Response includes mapping details

Supported Aliases

Standard Field	Also Accepts
vehicleId	vin, VIN, vehicle_id, fleet_id, asset_id
engine_speed	rpm, engine_rpm, engineRPM, motor_speed
coolant	coolant_temp, engine_temp, ect, water_temp
battery_voltage	battery, bat_v, voltage, batt_voltage
vehicleSpeed	speed, vehicle_speed, gps_speed, kph
obdDistance	odometer, odo, mileage, total_km, distance
fuel_level	fuel, tank, fuel_pct, tank_level
dtc_codes	dtc, fault_codes, faultCodes, error_codes

Example: Legacy Data

Your Data:

{
  "vin": "ABC123XYZ",
  "rpm": 2400,
  "coolant_temp": 92,
  "bat_v": 13.2
}

What Happens:

{
  "vehicleId": "ABC123XYZ",
  "predictions": { ... },
  "_schemaMapping": {
    "autoMapped": true,
    "mappedFields": {
      "rpm": "engine_speed",
      "coolant_temp": "coolant",
      "bat_v": "battery_voltage"
    }
  }
}

Best Practice

While auto-mapping works, using standard field names is recommended for:

• Best prediction accuracy
• Consistent results
• Future compatibility

---

Example Requests

Minimal Request

{
  "vehicleId": "TRUCK-001"
}

Recommended Request

{
  "vehicleId": "TRUCK-001",
  "timestamp": "2026-01-13T10:00:00Z",
  "engine_speed": 2400,
  "coolant": 92,
  "battery_voltage": 13.2,
  "fuel_level": 75,
  "vehicleSpeed": 65
}

Full Request

{
  "vehicleId": "TRUCK-001",
  "timestamp": "2026-01-13T10:00:00Z",
  "engine_speed": 2400,
  "coolant": 92,
  "engineOilTemp": 95,
  "battery_voltage": 13.2,
  "vehicleSpeed": 65,
  "fuel_level": 75,
  "fuel_consumption": 8.5,
  "obdDistance": 45000,
  "ambient_air_temperature": 28,
  "mil_lamp": "LAMP_OFF",
  "protect_lamp": "LAMP_OFF",
  "dtc_codes": [],
  "latitude": 12.9716,
  "longitude": 77.5946
}

---

Schema APIs

Get JSON Schema

GET /v1/schema/input

Returns the full JSON Schema for input validation.

Get Supported Aliases

GET /v1/schema/aliases

Returns all field aliases that are auto-mapped.

Get Processing Statistics

GET /v1/schema/statistics

Returns statistics on schema compliance:

{
  "total_processed": 1500,
  "fully_standard": 1200,
  "required_mapping": 300,
  "standard_compliance_rate": 80.0
}

---

Data Quality Impact

Fields Provided	Prediction Quality	Confidence
Only vehicleId	⚠️ Basic	Low
+ Core 5 fields	✅ Good	Medium
+ All optional fields	✅✅ Excellent	High
+ Historical data	✅✅✅ Best	Very High

---

Next Steps

• API Reference - Full endpoint documentation
• Getting Started - Deploy Axle Engine