# MQTT V2
The Enterprise MQTT broker enables you to subscribe to vehicle data updates and get them pushed to your application using the [MQTT protocol](https://mqtt.org/).
{% hint style="info" %}
**Endpoint URL**
The MQTT broker URL is `mqtt-v2.high-mobility.com:8883` for live and sandbox vehicle data
{% endhint %}
### 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`
```json
{
"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](https://app.gitbook.com/s/GqovsBFw7seb5vTEwucj/data/streaming-schema-v2 "mention")
```
{
"message_id": {Unique Message ID: string},
"application_id": {application uuid}
"version": 2,
"vin": {Vehicle Identification Number: string},
"data": {Auto API Schema: object}
}
```
{% hint style="info" %}
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.
{% endhint %}
### 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.
{% hint style="warning" %}
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](https://app.gitbook.com/o/7DAQOcBJC2VVRjtEi99E/s/iwCZtaJjx6U2nqCam6Do/ "mention")
* Currently you are not able to revoke client certificates, we are working on the implementation.
{% endhint %}
### 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:
```bash
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-' \
--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--` 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](https://docs.hivemq.com/hivemq/latest/user-guide/shared-subscriptions.html).
{% hint style="danger" %}
The client id format and shared subscription format must follow the documentation. We keep the right to enforce them via broker in future.
{% endhint %}
{% hint style="info" %}
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: `-`
{% endhint %}
### 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](https://docs.hivemq.com/hivemq/latest/user-guide/shared-subscriptions.html) 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).
{% hint style="info" %}
**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.
{% endhint %}
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](https://docs.high-mobility.com/docs/getting-started/fleet-clearance) guide depending on your specific application.
