Kafka API
Alongside our REST API, Hiboo also exposes a Kafka API for customers who need equipment data delivered as a continuous, low-latency stream rather than fetched on demand.
When to use the Kafka API
The REST API is the primary way to integrate with Hiboo and covers most use cases: fleet browsing, history, snapshots, and reporting. The Kafka API complements it when you need:
- Real-time data: events are pushed as soon as Hiboo processes them, with no polling delay.
- Push-based integrations: a natural fit for streaming pipelines, data lakes, and event-driven architectures.
- High-throughput ingestion: built to handle large fleets without the overhead of pagination or rate management.
Not sure which one you need? Start with the REST API. The Kafka API is an add-on for streaming use cases and requires a dedicated onboarding.
Authentication with mTLS
The Kafka API is secured with mutual TLS (mTLS). Unlike the REST API, it uses no x-access-token header: the client proves its identity with a certificate issued by Hiboo.
When your Kafka access is provisioned, Hiboo provides:
- A client certificate (
.crt) - A private key (
.key) - The CA certificate used to verify the broker (
ca.crt) - The list of bootstrap brokers and the topic you are authorized to consume
Treat the private key like any other secret: store it securely, never commit it to source control, and request a new one if you suspect it has been exposed.
Topic & message format
Each customer is provisioned with a single dedicated topic carrying all of their time-series data. There is no need to subscribe to multiple topics: every dataKind (positions, fault codes, fuel, operating hours, and so on) flows through the same stream.
Each message is a JSON object. The dataKind field tells you which type of data you are reading.
Key fields to know:
assetId: the Hiboo equipment identifier, matching theidreturned by the REST fleet endpoints.datetime: the UTC timestamp of the event (ISO 8601). Daily data kinds usedateinstead.dataKind: the type of data carried by the message. Use it to route each message to the right handler on your side.dataSourceCode: the source provider of the message.
Message types
Every message has the fields above. Each type below lists its dataKind and its other fields, then an example message.
Position
dataKind: position
Other fields: latitude, longitude, postalAddress, timezone, altitude, speed, heading, precision, origin
{
"assetId": 123456,
"datetime": "2026-04-22T14:49:07.000Z",
"dataKind": "position",
"dataSourceCode": "ocean",
"latitude": 48.85837,
"longitude": 2.294481,
"postalAddress": "5 Av. Anatole France, 75007 Paris, France",
"timezone": "Europe/Paris",
"altitude": null,
"speed": 26,
"heading": null,
"precision": null,
"origin": null
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "battery_voltage",
"dataSourceCode": "volvotrucks_connect",
"volts": 12.5
}
Fault codes
dataKind: fault_codes
Other fields: level, label, description, extraInfo, status, failureCategory, system
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "fault_codes",
"dataSourceCode": "volvotrucks_connect",
"level": 2,
"label": "D1DIG.1",
"description": "GPMECU - General Purpose Machine Electronic Control Unit 1",
"extraInfo": {"more": "data"},
"status": "fault",
"failureCategory": "threshold_exceeded",
"system": "refrigeration_unit"
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "sensor_boolean",
"dataSourceCode": "samsara",
"type": "checkEngineLights.stopIsOn",
"status": false
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_distance",
"dataSourceCode": "volvotrucks_connect",
"kilometers": 80853.3
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_usage_hours",
"dataSourceCode": "volvotrucks_connect",
"hours": 1802.4
}
Engine condition
dataKind: engine_condition
Other fields: running, engineNumber
running is a string: on, off or idle. The REST API gives the same state as a boolean running, true for on and idle.
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "engine_condition",
"dataSourceCode": "volvotrucks_connect",
"running": "on",
"engineNumber": "HC17007"
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "temperature",
"dataSourceCode": "samsara",
"type": "front - ambientTemperature",
"celsius": 21.96
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "battery_level",
"dataSourceCode": "volvotrucks_connect",
"percent": 87.5
}
Cumulative active regeneration hours
dataKind: cumulative_active_regeneration_hours
Other fields: hours
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_active_regeneration_hours",
"dataSourceCode": "volvotrucks_connect",
"hours": 120.5
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_fuel",
"dataSourceCode": "volvotrucks_connect",
"liters": 15234.7
}
Cumulative idle fuel
dataKind: cumulative_idle_fuel
Other fields: liters, engineNumber, tankDesignation
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_idle_fuel",
"dataSourceCode": "volvotrucks_connect",
"liters": 812.3,
"engineNumber": "1",
"tankDesignation": "main"
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_idle_hours",
"dataSourceCode": "volvotrucks_connect",
"hours": 342.25
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_load_count",
"dataSourceCode": "volvotrucks_connect",
"count": 4521
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_payload",
"dataSourceCode": "volvotrucks_connect",
"tons": 9876.5
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "cumulative_power_take_off_hours",
"dataSourceCode": "volvotrucks_connect",
"hours": 56.75
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "def_remaining_ratio",
"dataSourceCode": "volvotrucks_connect",
"percent": 64.0,
"tankCapacityLiters": 40.0
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "engine_coolant_temperature",
"dataSourceCode": "volvotrucks_connect",
"celsius": 88.5
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "engine_load_percentage",
"dataSourceCode": "volvotrucks_connect",
"percent": 42.0
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_battery_charge_cycles_count",
"dataSourceCode": "volvotrucks_connect",
"count": 312
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_battery_current",
"dataSourceCode": "volvotrucks_connect",
"amperes": 125.4
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_battery_health",
"dataSourceCode": "volvotrucks_connect",
"percent": 96.5
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_battery_level",
"dataSourceCode": "volvotrucks_connect",
"percent": 78.0
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_battery_temperature",
"dataSourceCode": "volvotrucks_connect",
"celsius": 31.5
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_battery_voltage",
"dataSourceCode": "volvotrucks_connect",
"volts": 398.2
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_charging_rate",
"dataSourceCode": "volvotrucks_connect",
"watts": 22000.0
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_charging_state",
"dataSourceCode": "volvotrucks_connect",
"state": "charging",
"chargingMode": "ac"
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_discharging_rate",
"dataSourceCode": "volvotrucks_connect",
"watts": 15000.0
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_energy_charged",
"dataSourceCode": "volvotrucks_connect",
"wattHours": 1250000
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "ev_energy_used",
"dataSourceCode": "volvotrucks_connect",
"wattHours": 980000
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "fuel_remaining",
"dataSourceCode": "volvotrucks_connect",
"percent": 55.5,
"tankCapacityLiters": 300.0
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "pressure",
"dataSourceCode": "samsara",
"type": "hydraulicOil",
"pascal": 250000.0
}
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "sensor_level",
"dataSourceCode": "samsara",
"type": "hydraulicOil",
"percent": 72.5
}
Tyre snapshot
dataKind: tyre_snapshot
Other fields: isoPositionIndex, flags, pressure, referencePressure, temperature, signalQuality, signalQualityScore
{
"assetId": 100,
"datetime": "2024-09-14T13:08:35.000Z",
"dataKind": "tyre_snapshot",
"dataSourceCode": "samsara",
"isoPositionIndex": 11,
"flags": [
"low_pressure"
],
"pressure": 7.2,
"referencePressure": 8.5,
"temperature": 24.0,
"signalQuality": "good",
"signalQualityScore": 0.92
}
Getting access
The Kafka API is not self-service. To request access:
- Contact us at support@hiboo.io with your use case and expected volume.
- Our team provisions your certificates and shares the broker endpoints.
- Connect from any Kafka-compatible client (Java, Python
confluent-kafka, and others) configured for mTLS.