Connected Fleet API Push Documentation

Overview

MOBITO has developed a highly available Push API for data delivery that allows consumers to access their vehicle fleet data. In this document, we will provide step-by-step instructions to help you integrate our API with your tech stack.

Before you begin

The Push API is based on Apache Kafka which offers a platform designed for efficiently managing real-time data feeds with high throughput and minimal latency. Our API utilizes Kafka to transmit timely updates of vehicle signals to your systems. To learn more about Kafka, please explore the official Kafka website.

This tutorial will assume that you have provided MOBITO with the VINs of your fleet. After that, you will need the following:

Kafka Broker URL: The connection URL for our Apache Kafka cluster
Access Credentials: These are basic authentication credentials consisting of a username and a password which will provide read access to your dedicated Kafka topic
Your customer specific Kafka topic: The name of the topic where you will receive messages, one for production and one for non-production.

You will receive all the above as part of the customer onboarding procedure.

Sample messages and code examples for connecting to Kafka can be found in the following sections. We use Node.js for our examples but be sure to visit the official Kafka connection library for your language of choice if needed.

How to connect

Once a vehicle (VIN) has been registered, it begins to generate vehicle signals that you can receive using the Push API. It allows you to consume them via your own customer-specific Kafka topic. Security policies assure that none else can access your topic.

To consume messages you need a Kafka message consumer, the consumer configuration, and your credentials. The consumer configuration includes the URL of the Push API as well as the topic name.

The topic name is customer-specific. For more information, please refer to the section Before you begin in this document. There are various messaging clients available for Kafka in a variety of programming languages, e.g., for Java as documented in the Consumer API section of the Apache Kafka Documentation. In this example, we use the kafkajs library for Node.js.

Example

In this example, we connect to the Kafka cluster and log messages upon consumption. You will need an installation of Node.js & npm.

Create a directory called kafka-example and navigate to that directory.
Initialize the project and install the kafkajs library:
Terminal window
```
npm init -y
npm install kafkajs
```

Create an index.js file and initialise your configuration constants

const BROKER_URL = '<BROKER_URL>';
const USERNAME = '<USERNAME>';
const PASSWORD = '<PASSWORD>';

Add a handler for each message received and log it.

// Log messages example
 consumer.run({
 eachMessage: async ({topic, partition, message}) => {
     console.log({
         topic,
         partition,
         offset: message.offset,
         value: message.value.toString(),
     });
   },
 });

After you’re done, disconnect from the cluster
Terminal window
```
consumer.disconnect();
```

Message schema example

There is no Async API specification as of right now, but you can find an example event below.

{
    "display_unit_distance": "km",
    "position_can_be_trusted": true,
    "distance_until_service": "11000",
    "service_date": 71,
    "condition_based_services_count": 9,
    "vehicle_check_status": "OK",
    "vehicle_check_status_remaining_distance": 35000,
    "vehicle_check_status_date": "2027-02",
    "brake_fluid_due_date": "2026-02",
    "vehicle_inspection_due_date": "2027-04",
    "engine_oil_remaining_distance": 11000,
    "brake_fluid_status": "OK",
    "vehicle_inspection_status": "OK",
    "code_CBSHUAU": 4,
    "fuel_level": 47,
    "tire_pressure_front_left": "207",
    "tire_pressure_rear_left": "186",
    "tire_pressure_front_right": "221",
    "tire_pressure_rear_right": "200",
    "tire_pressure_target_front_left": "234",
    "dtc_data": "[3178A, B7F34E, 804070, 804081, 800ABF, B7F500, 31796, 31790, B7F8C6]",
    "tire_pressure_target_front_right": "234",
    "avg_distance_short_term": "680.0",
    "avg_distance_long_term": "680.0",
    "tire_pressure_target_rear_left": "214",
    "tire_pressure_target_rear_right": "214",
    "average_mileage_per_week": 1082,
    "mileage_forecast": 21260,
    "remaining_contract_days": 45,
    "tank_capacity": "42.0",
    "service_status": "OK",
    "service_due_date": "2025-02",
    "mileage": "14312.0",
    "model": "118i",
    "fuel_remaining_range": "276.0",
    "teleservice_status": "Initial status",
    "engine_oil_due_date": "2025-02",
    "engine_oil_status": "OK",
    "yellow_service_time": 4,
    "basic_has_sun_roof": false,
    "basic_construction_date": "2023-02-16T00:00:00Z",
    "basic_engine": "B38C",
    "basic_color_code": "C3N",
    "legal_inspection_date": "01.04.2027 00:00:00 UTC",
    "lsc_trigger_reason": "CONV",
    "basic_propulsion_type": "BE",
    "basic_country_code": "GR",
    "basic_head_unit": "HU_MGU",
    "brand": "BMW",
    "yellow_service_distance": "2000",
    "battery_voltage": "12.56",
    "engine_coolant_temperature": 63,
    "vehicle_is_locked": "UNLOCKED",
    "check_control_messages": "[955 Tire pressure notification]",
    "latitude": "36.82235111111111",
    "longitude": "21.719039166666665",
    "altitude": "11.0",
    "heading": "338.0",
    "remaining_fuel": "17.0",
    "basic_model_key": "7K31",
    "basic_has_Navi": true,
    "series": "1",
    "colour_code": "STORM BAY METALLIC",
    "number_of_doors": 5,
    "steering": "LL",
    "extra_equipment": "01CB,01DF,01DZ,0230,0249,026M,02PA,02TF,02VB",
    "power": "100",
    "capacity": 1499,
    "data_quality": "UP_TO_DATE",
    "basic_body_type": "Sports Hatch",
    "basic_model_range": "F40",
    "doors_front_left_is_open": "false",
    "doors_rear_left_is_open": "false",
    "doors_ront_right_is_open": "false",
    "doors_rear_right_is_open": "false",
    "vin": "EXAMPLE0607M29923",
    "fleet_id": "ExampleFleetId",
    "uuid": "31f460d8-92eb-427a-9487-3611c2670608"
}