MQTT V2

Use the Enterprise MQTT broker to subscribe and stream live vehicle data updates over MQTT

The Enterprise MQTT broker enables you to subscribe to vehicle data updates and get them pushed to your application using the MQTT protocol.

Endpoint URL

The MQTT broker URL is mqtt-v2.high-mobility.com:8883 for live and sandbox vehicle data

Topic and message structure

All messages that are published into single topics.

Here's an example of the JSON that would be sent for the odometer, coordinates and altitude data:

Topic: live/level13/00000000-0000-0000-0000-000000000000

{
  "version": 2,
  "application_id": "00000000-0000-0000-0000-000000000000",
  "message_id": "4F02FFB01650060FA8888E5C3ED46FF2A0E4A49EACF1A92E264CD0C137971B28",
  "vin": "EXV10000000",
  "data": {
    "diagnostics": {
      "odometer": [
        {
          "data": {
            "unit": "kilometers",
            "value": 19201.01
          }
        }
      ]
    },
    "vehicle_location": {
      "altitude": [
        {
          "data": {
            "unit": "meters",
            "value": 63
          },
          "timestamp": "2025-08-12T16:07:48.000Z"
        }
      ],
      "coordinates": [
        {
          "data": {
            "latitude": 11.572,
            "longitude": 8.487
          },
          "timestamp": "2025-08-12T16:07:48.000Z"
        }
      ]
    }
  }
}

Message

Here is the JSON format that is used for every message that is published. All data objects, that hold the specific car data payload, are formatted according to the Streaming Schema V2

{
   "message_id": {Unique Message ID: string},
   "application_id": {application uuid}
   "version": 2,
   "vin": {Vehicle Identification Number: string},
   "data": {Auto API Schema: object}
}

Our system is designed to guarantee at-least-once delivery of each message. Please consider the possibility that a message_id is delivered more than once.

Authentication

Head to your project's "API Credentials"->"Streaming" section. Select "MQTT V2(Enterprise)" and click the "Save and update" button.

After that you are able to download certificate via "Add MQTT V2 Client Certificate" section.

Few important notes:

• When you switch the streaming method, it takes ~1h for the change to propagate, during that period you still receive the data using your previous streaming method

• You can only download 5 client certificate per project per environment. If you are in a situtuon which you need more, please contact us Help Center

• Currently you are not able to revoke client certificates, we are working on the implementation.

Connect

The file you downloaded in the previous step also includes a file called snippet.txt, which contains the required options to run an MQTT client from the terminal using mosquitto_sub.

You may use any MQTT client software or library you prefer. When connecting. Do not omit any of the suggested options; otherwise, your mqtt client may miss some vehicle data.

The following example shows how mosquitto_sub is used to both connect and subscribe to all messages:

mosquitto_sub \
              --cafile ca_crt.pem \
              --cert client_crt.pem \
              --key client_key.pem\
              --host mqtt-v2.high-mobility.com \
              --port 8883 \
              --qos 1 \
              -V 5 \
              --id '879577a3-b25f-4a28-8c0e-7effcc7682a2-sandbox-<rnd-number>' \
              --disable-clean-session \
              --topic '$share/879577a3-b25f-4a28-8c0e-7effcc7682a2/sandbox/level13/879577a3-b25f-4a28-8c0e-7effcc7682a2#'
        

The following parameters are needed for the connection:

• --cafile, --cert , --key which you can find in the zip file.

• -qos: Set the QoSto 1 in order to guarantee that a message is delivered at least once.

• -V : Set the MQTT version to 5. While our broker support MQTT 3, we highly recommend to use version 5.

• --id: Client ID. Please use your application-id-<sandbox/live>-<with some random id> as suffix.

• --disable-clean-session : This option is needed to queue your data in the broker when your mqtt client is down. Please refer to rest the doc about the max queue size.

• --topic : the topic include share group name $share/879577a3-b25f-4a28-8c0e-7effcc7682a2 and the topic we want to subscribe to sandbox/level13/879577a3-b25f-4a28-8c0e-7effcc7682a2/#. You can read more about shared subscription at here.

The client id format and shared subscription format must follow the documentation. We keep the right to enforce them via broker in future.

Each client certificate can be used for as many active connections as you need. The only limitation is that you cannot connect two clients with the same client_id to an MQTT broker at the same time.

We Suggest to use client with the following format: <your-project-id>-<random-number>

Subscribe

Once you have connected, go ahead and subscribe to any topic path that matches your application id. Here are a few common use-cases:

• To subscribe to all data updates, pass in live/level13/{application_id}. Replace live with sandbox if you are working with the simulator.

• Use MQTT shared subscriptions to distribute messages across multiple consumers and speed up data ingestion.

  • With a shared subscription, messages are load-balanced between consumers in the same group, increasing overall throughput.

  • The shared subscription group has a queue size of 500,000 messages (as opposed to 10,000 messages for a non-shared subscription).

HEADS UP

• Please note that the the data is not guaranteed to be delivered in a chronological order. The timestamp of each MQTT message payload will always tell you at what time the data was generated in the vehicle.

• If your consumers aren’t fast enough to keep up, older messages will be dropped once the queue limit is reached.

You will now get vehicle data delivered to you for all vehicles that have approved access grants. To receive an access grant, have a look at the Fleet Clearance guide depending on your specific application.