# Home Welcome to your team’s developer platform Welcome to the High Mobility Docs! Here you'll get an overview of all the features, APIs and brands that we support. {% hint style="info" %} The High Mobility's old docs are available via {% endhint %} {% columns %} {% column %} ### Get started in 6 minutes Setting up your first API call should be the easiest part of getting started. Configure your app, clear endpoints, ready made postman collection, and quick authentication, you’ll be up and running in minutes to access our sandbox environment. No guesswork, no complexity—just your first successful call, fast. Get started API reference {% endcolumn %} {% column %} {% embed url="" %} {% endcolumn %} {% endcolumns %}

### :dev: Getting started for technical team To get familiarize yourself with APIs we suggest the following pages: * [OAuth 2.0](/docs/oauth-2.0): Quick way to authenticate your application. * [Vehicle Eligibility](/docs/vehicle-eligibility): A quick way to verify if your vehicles. * [Fleet Clearance](/docs/getting-started/fleet-clearance): Simple CRUD API to manage the vehicles in your application. * [Vehicle Data](/docs/vehicle-data): use these APIs and Streaming providers to get the state of vehicle. ### :business-time: Getting started for business team If you want to have an overview of supported brands and vehicle models, head to [OEM Guides](https://docs.high-mobility.com/oem-guides/) # Welcome In this section you'll find easy to follow guides to help you to integrate your system with High Mobility's APIs and Streaming interfaces. ### Jump right in

:bolt:

QuickstartConnect your first car/pages/7FvWQMF0kTK7HGhlQfmo

:globe-pointer:

Publish your applicationConfigure and enable your app/pages/tVE77yI3POmK3kOdOqwd
# Quickstart {% embed url="" %} # Fleet Clearance Manage vehicle data access by adding, approving, or revoking VINs with the Fleet Clearance API The Fleet Clearance API enables fleet owners and fleet solution providers to manage data access for their vehicles. It offers endpoints to: * **Add vehicle VINs** to a production or sandbox application. * **Retrieve a vehicle’s status** to check if it has been approved. * **Remove vehicles** that are no longer part of the fleet. {% hint style="info" %} In order to follow the guide you need to create an account in You can follow along using this doc using our Sandbox instance. {% endhint %} Visit [Console](https://console.high-mobility.com/) and create a project, Go to "Car Data" of your project and select properties that you are interested in for each brand. After that go to "API Credentails" and copy your "OAuth Client Credentails" in Sandbox instance to continue the guide. ### Getting Access Token With the app set up, it's time to use the Fleet Clearance API to add a vehicle and to retrieve data from it. To authenticate with any of the endpoints, you first have to create an OAuth2 Access Token. ```bash curl --location 'https://sandbox.api.high-mobility.com/v1/access_tokens' \ --header 'Content-Type: application/json' \ --data '{"client_id": "a92cf969-e8ff-4ad4-a45f-42930edde12d", "client_secret": "xfVxR6xnlbeVHXkQatRx4FmxSJxFR0-M", "grant_type": "client_credentials"}' { "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTgwNzAwMDEsImlhdCI6MTY5ODA2OTcwMSwiaXNzIjoiaHR0cHM6Ly9zYW5kYm94LmFwaS5oaWdoLW1vYmlsaXR5LmNvbS92MS9hdXRoX3Rva2VucyIsInNjb3BlIjoiZmxlZXQ6Y2xlYXJhbmNlIHZlaGljbGU6ZWxpZ2liaWxpdHktY2hlY2sgdmVoaWNsZTpkYXRhIiwic3ViIjoiMjEwZmMyOTUtZDQ5OS00ZDgwLTk5MWUtZTQ3NTZlZDI3YTZmIiwidmVyIjoxfQ.2neMW6LioKvZYlbSTf-W4GwSHQmMr_8cyXfhyi4XJF-6F4HrvFNIsLlNUa93wp6BiJ_XEythR8DfWh0PrIaHrg", "expires_in": 300, "scope": "fleet:clearance vehicle:eligibility-check vehicle:data", "token_type": "bearer" } ``` See the authentication tutorial for [OAuth2 Client Credentials](/docs/oauth-2.0) to get the full details and integration options. ### Getting clearance for a vehicle Before data can be retrieved for a vehicle, it has to be cleared for access. The clearance procedure is different for each carmaker and should be considered an asynchronous process. It's possible to clear one or many vehicles at the same time, and this is done by passing in the Vehicle Identification Numbers (VINs). You can use `2HM00000000000001` sandbox virtual VIN in sandbox which emit data every 1 min. ```bash curl --location --request POST 'https://sandbox.api.high-mobility.com/v1/fleets/vehicles' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5c...fWh0PrIaHrg' \ --data-raw '{"vehicles": [{"vin": "2HM00000000000001", "brand": "sandbox"}] }' ``` {% hint style="info" %} Additional resources: * Check out the [Open API Specification](/api-references/fleet-management/fleet-clearance) to see the reference of the `POST /fleets/vehicles` and `GET /fleets/vehicles` endpoints. * See the Activation Process guide for a detailed description of what happens under the hood during the clearance. {% endhint %} If you want to cancel the clearance of a vehicle, go ahead and use the `DELETE /fleets/vehicles/{vin}` endpoint. Similarly to when adding a new vehicle for clearance, this endpoint is asynchronous. Once the request has been processed the vehicle will be set to `canceled` or `revoked` depending on if the activation was still pending or not. Subscribe to the `fleet_clearance_changed` webhook to receive a notification once the clearance state changes to any of the possible value approved, revoked, rejected, canceled. Read more about the available notifications on the [webhooks](/docs/webhooks) page. #### Reject & Reason If a vehicle can not be activated the status is set to `rejected` or kept `pending` for further retries. Usually this means that the vehicle is not equipped with telematics hardware, however there could be other reasons as well. When we have specific information on why the activation failed we add a reject or pending reason to the clearance object. Here's an example: ```json { "vin": "VIN0TESTVIN000000", "status": "rejected", "brand": "volkswagen", "changelog": [ { "timestamp": "2025-01-12T09:36:51", "status": "pending" }, { "timestamp": "2025-01-22T10:42:14", "status": "rejected", "reason": "privacy mode is enabled" } ] } ``` #### Using tags It is possible to store additional metadata together with each individual VIN clearance by using tags. Tags are key/value objects that you can use to store specific information such as: * Identifiers that reference your internal database records * Categorisation for your use-cases * Segmentation for sub-fleets The following shows an example of how vehicle clearance objects are passed in with a tag set: ```bash curl --location --request POST 'https://sandbox.api.high-mobility.com/v1/fleets/vehicles' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5c...fWh0PrIaHrg' \ --data-raw ' { "vehicles": [ { "vin": "VIN012345678901234", "brand": "audi", "tags": { "vw-group-customer-name": "Car Operations Ltd." } } ] } ' ``` ### Revoking clearance It's possible to revoke a clearance at any point of time, which stops the data access immediately. This is especially important when a vehicle is being defleeted. To do this, you just need to use the `DELETE /fleets/vehicles/{vin}` endpoint, which will update the status to `revoking` and then to `revoked` once the deactivation has completed. It's also possible to cancel the clearance procedure for [**some brands**](/docs/getting-started/fleet-clearance/activation-process#pending-state) vehicles that still are pending, which changes the state to `canceled`. ```bash curl --location --request DELETE 'https://api.high-mobility.com/v1/fleets/vehicles/2HM00000000000001' \ --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5c...fWh0PrIaHrg' ``` ### Sandbox virtual VINs When you are working with our sandbox API, you can perform the fleet clearance using the VINs of any of your vehicle simulators. The clearance is always approved in a matter of seconds. \ To provide additional testing opportunities, the sandbox API also accepts the following virtual VINs. What's special about these VINs is that they have a predetermined behaviour that allow you you to simulate different real-life scenarios. In addition, a virtual VIN may support REST API requests (pull) and streaming (push). | VIN | BRAND | DESCRIPTION | | ----------------- | ------- | ----------------------------------------------------------------- | | 2HM00000000000001 | sandbox | Pull enabled, Push every 1 min | | 2HM00000000000002 | sandbox | The clearance never succeeds or fails, stays in a `pending` state | | 2HM00000000000003 | sandbox | The clearance is `rejected` after 3 hours | ### Data delivery You can start getting vehicle data via Rest-API using vehicle data apo ```bash curl --location 'https://sandbox.api.high-mobility.com/v1/vehicle-data/autoapi-13/2HM00000000000001' \ --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5c...fWh0PrIaHrg' \ { "brand": "sandbox", "diagnostics": { "odometer": { "data": { "unit": "kilometers", "value": 2059 }, "failure": null, "timestamp": "2023-09-22T13:27:26.715Z" } }, "vin": "2HM00000000000001" } ``` If you have enabaled streaming via the MQTT interface, the data will be put onto the stream automatically upon activation. ```bash mosquitto_sub --disable-clean-session \ --cafile root.pem \ --cert certificate.pem.crt \ --key private.pem.key \ -h mqtt.sandbox.high-mobility.com \ -p 8883 \ -q 1 \ -t 'sandbox/level13/1FBBEDED80595912588FF4FF/#' \ -i '75374841-d7a5-4db7-b9b5-8a5f60eed79d' ``` ### More Information If you have any questions, please contact us on [Slack](https://slack.high-mobility.com/) or [get in touch with our support](https://high-mobility.com/support/). # Activation Process Understand the vehicle activation process, its possible delays, and the states from pending to approved or rejected There are many things going on in the background during a vehicle activation process. In an ideal scenario it would be possible to start retrieving data as soon as you add a vehicle, however there are factors that can cause it to take several days before the first data becomes available. 1. The vehicle needs one or several Over-The-Air (OTA) updates to activate data upload. 2. Although activation has succeeded, the vehicle might need to be driven in order to generate new data. 3. In some cases manual intervention is needed if the vehicle privacy mode is turned on. However as soon as the first data starts to come in, no further delays should be expected. This guide explains the different states you can observe and explains differences from brand to brand. ### Vehicle state flow Whenever you add a new vehicle using the `POST /fleets/vehicles` endpoint, an asynchronous process is started to activate data access. We always keep a state of the vehicle activation, which can be one of `pending`, `approved`, `rejected`, `revoking`, `revoked`, `canceling`, `canceled` or `error`. {% hint style="info" %} Here's a few hints for your implementation: 1. It's possible to see the status of all vehicles using the `GET /fleets/vehicles` endpoint. 2. Subscribe to the `fleet_clearance_changed`webhook to get notified about any state changes {% endhint %} The following chart shows the state changes along with further descriptions below. \ \ ![](/files/GsQvSoliXA7VmQeFz1ig) #### Pending state Once you add a vehicle it is by default in the pending state, which means that we are processing its activation. It should be considered that the activation can take several days or more. If the vehicle software is up to date the activation succeeds faster, as otherwise Over-The-Air (OTA) updates might be required. If the vehicle remains in the pending state there are a few things that you can check on your side: 1. Make sure that the vehicle is being driven. If several OTA updates need to be applied, the vehicle has to be driven several times. 2. The vehicle has to have privacy mode turned off, which can be checked in the vehicle settings screen. If you have controlled the above but can not get the vehicle activated, get in touch with us on . It's possible to cancel the activation process for some vehicles that are in the pending state through the API, it depends on the brands and it will set the vehicle to `canceled`. The brands that support clearance cancelation are: * Stellantis brands: alfaromeo, citroen, ds, fiat, jeep, maserati, opel, peugeot, vauxhall * Mercedes Benz: mercedes-benz * Volkswagen brands: volkswagen, audi, skoda, seat, cupra #### Generating new data We always return the latest available data when you perform a request after the vehicle clearance. If the request is done right after the vehicle state is set to `approved`, there might not have been any new data being generated since the activation. You will start to receive data as soon as the vehicle is being driven the next time. ### Pending and reject reasons \ If we detect that a vehicle can not be activated, depending on the situation, the vehicle will either stay as `pending` while we retry, or it will be marked as `rejected`. In both of these cases we return a reason for the delay or failure. This information is included with the clearance object that you can always inspect using the `/v1/fleets/vehicles` as described on the [Fleet Clearance API](broken://spaces/GqovsBFw7seb5vTEwucj/pages/e3dc80cb7ed2c3f7524aacc7a422fc0e05f7b4a4#get-v1-fleets-vehicles) page. example of a rejection reason JSON response: ```json { "vin": "VIN0TESTVIN000000", "status": "rejected", "brand": "volkswagen", "changelog": [ { "timestamp": "2025-01-12T09:36:51", "status": "pending" }, { "timestamp": "2025-01-22T10:42:14", "status": "rejected", "reason": "privacy mode is enabled" } ] } ``` Here's a breakdown of the most common pending and reject reasons. Due to the dynamic nature of the failures the reason is returned as a string in the `reason`field of a clearance object.
### Pending reasons | BRAND | REASON | DESCRIPTION | | ---------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Ford | consent assignment missing | Fleet operator consent to High Mobility is missing in the OEM portal. | | Stellantis Group, Volkswagen Group | no data received | We haven't receive data from the vehicle . | | Volkswagen Group | privacy mode is enabled | The vehicle has privacy mode enabled, which blocks the activation process. We will keep retrying for a number of days before the vehicle is set to `rejected` | ### Reject reasons | BRAND | REASON | DESCRIPTION | | --------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Global | unspecified | When an activation fails without any specific reason, this reason is returned. For many brands this means that the vehicle is not eligible. | | Global | invalid client configuration | This indicates that your project has not been configured by our support team. Please get in touch with your contact person. | | Global | invalid VIN | The VIN is not recognised by the manufacturer as an eligible vehicle. | | Global | ineligible VIN | The vehicle is not eligible for activation. | | Global | VIN is assigned to a different OEM fleet | The VIN is already activated by another customer of the OEM, which blocks High Mobility from activating it. | | BMW Group, Toyota Group, VW Group, Polesta | VIN is assigned to a different app or project | The VIN is already activated in a different project. Multiple project activation is not possible for these brands. | | Ford, Tesla | consent assignment missing | Fleet operator consent to High Mobility is missing in the OEM portal. | | Ford | invalid OEM state: VIN revoke in progress | Ford is still processing a previous request to revoke the VIN, which needs to finish before a new clearance can be created | | Mercedes-Benz | VIN activation timeout | The activation of the VIN has timed out as the vehicle could not be reached after several days of retrying. | | Stellantis Group | telematics hardware error | There is an issue with the telematics hardware in the vehicle. Please get in touch with our support team. | | Renault Group | invalid OEM state | There is an unknown error in the Renault activation API. Please get in touch with our support team. | | VW Group, Renault Group, Volvo Cars, Polestar, Stellantis | OEM fleet assignment failed | The VIN is most likely activated by another customer of the OEM. Please get in touch with our support team. | | VW Group | customer name tag missing | The fleet operator name is missing in the clearance request. Retry with the `vw-group-customer-name` tag set. | | VW Group | privacy mode is enabled | The vehicle has privacy mode enabled, which blocks the activation process. | | VW Group | ineligible or constrained VIN | The vehicle is either not eligible for activation, or in rare cases, its activation is blocked by VW. | | VW Group | vehicle platform not supported | The vehicle is on an OEM platform which doesn't support fleet activation. | | VW Group | primary user enrolled | The vehicle has primary user enrolled, the user must be deregistered and head-unit need to be reset before trying aging. | | VW Group | software version incompatible | The software in vehicle is incompatible. Please get in touch with our support team. | | Stellantis Group, Volvo Cars | activation timeout: no data | We failed to receive any data from the vehicle during the activation process. | | Kia | in-vehicle connectivity settings are disabled | Vehicle's connectivity is not activated | | Kia | VIN activation not allowed by OEM | | # OAuth 2.0 Authenticate your apps with OAuth 2.0 to generate short-lived access tokens for vehicle and fleet APIs Our [OAuth 2.0 API](https://www.oauth.com/) with the `client_credentials` grant type allows you to create access tokens to manage your application resources. It's also possible for fleet solutions to use the REST API to retrieve vehicle data for any of their fleet vehicles. You can use the access tokens to authenticate with any of the following services: * [Data API](/api-references/data/vehicle-data/data-api) * [Eligibility](/api-references/fleet-management/eligibility) * [Static Data API](/docs/vehicle-data/static-data-api) * [Broken mention](broken://spaces/GqovsBFw7seb5vTEwucj/pages/e3dc80cb7ed2c3f7524aacc7a422fc0e05f7b4a4) We offer two different alternatives for creating an access token, both compliant with the OAuth2 standard. * The first one is to use [client credentials grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) by authenticating with your Client ID and Client Secret. * As a second option, you can use [assertions for client authentication](https://datatracker.ietf.org/doc/html/rfc7521#section-4.2) by generating private keys within our console and use your private key to authenticate using JWTs. You can choose the option that best fits your system design and software architecture. ### Client ID & Client Secret In order to get an access token, head to your application "OAUTH CLIENT" section in the console and copy the `client_id` and `client_secret`. Next you can make an API call to create a an access token: ```bash curl --location 'https://sandbox.api.high-mobility.com/v1/access_tokens' \ --header 'Content-Type: application/json' \ --data '{"client_id": "a92cf969-e8ff-4ad4-a45f-42930edde12d", "client_secret": "xfVxR6xnlbeVHXkQatRx4FmxSJxFR0-M", "grant_type": "client_credentials"}' { "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTgwNzAwMDEsImlhdCI6MTY5ODA2OTcwMSwiaXNzIjoiaHR0cHM6Ly9zYW5kYm94LmFwaS5oaWdoLW1vYmlsaXR5LmNvbS92MS9hdXRoX3Rva2VucyIsInNjb3BlIjoiZmxlZXQ6Y2xlYXJhbmNlIHZlaGljbGU6ZWxpZ2liaWxpdHktY2hlY2sgdmVoaWNsZTpkYXRhIiwic3ViIjoiMjEwZmMyOTUtZDQ5OS00ZDgwLTk5MWUtZTQ3NTZlZDI3YTZmIiwidmVyIjoxfQ.2neMW6LioKvZYlbSTf-W4GwSHQmMr_8cyXfhyi4XJF-6F4HrvFNIsLlNUa93wp6BiJ_XEythR8DfWh0PrIaHrg", "expires_in": 300, "scope": "fleet:clearance vehicle:eligibility-check vehicle:data", "token_type": "bearer" } ``` In this example you can see how the access token is included as the authorization bearer for retrieving the eligibility state of a vehicle. ```bash curl --location 'https://sandbox.api.high-mobility.com//v1/eligibility' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTgwNzAwMDEsImlhdCI6MTY5ODA2OTcwMSwiaXNzIjoiaHR0cHM6Ly9zYW5kYm94LmFwaS5oaWdoLW1vYmlsaXR5LmNvbS92MS9hdXRoX3Rva2VucyIsInNjb3BlIjoiZmxlZXQ6Y2xlYXJhbmNlIHZlaGljbGU6ZWxpZ2liaWxpdHktY2hlY2sgdmVoaWNsZTpkYXRhIiwic3ViIjoiMjEwZmMyOTUtZDQ5OS00ZDgwLTk5MWUtZTQ3NTZlZDI3YTZmIiwidmVyIjoxfQ.2neMW6LioKvZYlbSTf-W4GwSHQmMr_8cyXfhyi4XJF-6F4HrvFNIsLlNUa93wp6BiJ_XEythR8DfWh0PrIaHrg' \ --data '{ "vin": "2HM00000000000001", "brand": "sandbox" }' { "data_delivery": [ "pull", "push" ], "eligible": true, "vin": "2HM00000000000001" } ``` The access token is valid for 5 minutes and can be used for any of the endpoints that are listed as the scope. The Token URI is listed in your application page in the console and differs between our sandbox and live data environments. ### JWT-Based Client Assertion In this type of authenticaion supports client auth using JWT assertions signed with asymmetric key pairs. {% hint style="info" %} **WHEN TO USE?** While we recommand to use `client_id` and `client_secret` to authenticate, in some circumstances based on your requirements and internal policies you might want to use this approach. {% endhint %} The steps are as followed: 1. Create a "OAuth Client Credentials" in the console for your application 2. Sign a JWT with the required claims 3. Call the `/v1/access_tokens` endpoint to get an access token. The parameter `client_assertion_type` must be included and set to `urn:ietf:params:oauth:client-assertion-type:jwtbearer` . 4. Use the `access_token` value in the subsequent API calls. The following snippet shows an example of how a JWT is generated using the private key, and how the access token is used for authentication in a subsequent API request. ```javascript const jwt = require("jsonwebtoken") const uuid4 = require('uuid4') const request = require("request-promise"); var config = { client_id: "my-client-id", "inserted_at": "2020-06-22T09:38:09", "private_key": "-----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----", "id": "f6c331c4-9271-4e3b-a8c4-6a2cacac6451" } function get_jwt_token() { var payload = { ver: 2, iss: config.id, aud: "https://sandbox.api.high-mobility.com/v1", jti: uuid4(), iat: Math.round(Date.now() / 1000), } const private_key = Buffer.from(config.private_key, 'utf8') return jwt.sign(payload, private_key, { algorithm: 'ES256' }) } async function get_client_credentials_access_token(client_assertion) { const response = await request.post({ url: 'https://sandbox.api.high-mobility.com/v1/access_tokens', json: { client_assertion: client_assertion, grant_type: "client_credentials", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" } }) return response } async function get_eligibility_check(access_token) { const response = await request.post({ url: 'https://sandbox.api.high-mobility.com//v1/eligibility', headers: { "Authorization": `Bearer ${access_token}`, "Content-Type": "application/json" }, json: { vin: "2HM00000000000001", brand: "sandbox" }, }) return response } async function main() { try { const client_assertion = get_jwt_token() const access_token_response = await get_client_credentials_access_token(client_assertion) const eligibility_response = await get_eligibility_check(access_token_response.access_token) console.log(eligibility_response) console.log("Done") } catch (err) { console.error("Error in main:", err); } } main(); ``` ### OpenAPI Specification You can see all endpoint specifications on the [OpenAPI Reference](/api-references/auth/oauth2) page. # Vehicle Data Review of different Vehicle Data APIs High Mobility provides several ways to deliver vehicle data. In this section, we give an overview of the available methods and when to use each one.
#### REST API This API provides access to the last known state of a vehicle. While it is simple to use, we recommend limiting it to integration testing only. Avoid polling this API every few minutes for each vehicle, as the state is not persisted between calls. The general use case is when you do not need a continuous stream of data, but instead want to **collect data points once or twice per day**. For production and professional use cases, we strongly recommend using push-based methods instead. [Read more about REST API integration](/docs/vehicle-data/rest-api) #### MQTT V1 MQTT is a well-known technology with many client libraries available in different programming languages. We recommend using MQTT if you manage a fleet of fewer than 1,000 vehicles. We are currently working on improving our MQTT broker to better support larger fleets and will provide updates once it is ready. [Read more about MQTT V1 integration](/docs/vehicle-data/mqtt-v1) #### AWS Kinesis This integration uses Amazon Web Services Kinesis, a real-time data streaming service. You need an AWS account, a configured Kinesis stream, and to grant High Mobility access to it. Choose this method if you need to consume data as quickly as possible. It scales seamlessly with your growth and does not impose limitations. [Read more about AWS Kinesis integration](/docs/vehicle-data/aws-kinesis) #### AWS S3 This integration works with Amazon Web Services S3, a cloud object storage service. You need an AWS account, an S3 bucket, and to grant High Mobility access to it. This approach is suitable when real-time data is not required, and a delay of up to 5 minutes is acceptable. It also allows you to leverage the wide ecosystem of third-party tools that integrate with S3 for data processing and analytics. [Read more about AWS S3 integration](/docs/vehicle-data/aws-s3) #### Azure Blob Storage This integration works with Azure Blob Storage , a cloud object storage service. You need an Azure account, an Blob Storage, and to grant High Mobility access to it. This approach is suitable when real-time data is not required, you can configure data delivery in great details. It also allows you to leverage the wide ecosystem of third-party tools that integrate with Blob Storage for data processing and analytics. [Read more about Azure Blob Storage integration](/docs/vehicle-data/azure-blob-storage) #### Static Data API The Static Data API(Beta) enables you to perform build information lookups for vehicles in your fleet. The data is provided by [DAT Group](https://www.datgroup.com/) and we offer the convenience of retrieving the information via our platform [Read more about Static Data API](/docs/vehicle-data/static-data-api) # REST API Learn how to use the Vehicle Data API to retrieve car data The Vehicle Data API lets you work with car data on any platform using a REST API. This tutorial will help you get started and show you how to work with it. By following the steps you will be receiving odometer data from the car simulator. {% hint style="info" %} **ENDPOINT URL** Note that the REST API base URL is when working with the sandbox vehicles and for live vehicle data. When you use the configuration snippets from the platform as shown in this tutorial, you will always be using the right URL automatically. {% endhint %} ### 1. Create an application Visit the [Console](http://console.high-mobility.com/), create an application and select the data which are intrested in. ### 2. Create a simulator In the "Simulation studio" you are able to create vehicles to link with your app and to test with the simulators. Go to the simulation studio and click the big plus (+) button. ### 3. Link Vehicle and Retrieve Access Token Now to use the REST API you will need to create an Access Token. Follow the [Fleet Clearance](/docs/getting-started/fleet-clearance) guide for fleet vehicles. ### 4. Send a Request Once the simulator is open, fire away a request. For example to get the diagnostics state of the vehicle. If you see that the app lacks permissions, you will need to revisit step two of the "[Create an application](#id-1.-create-an-application)" section of this document and select the appropriate permissions for your telematics command. ```javascript const request = require('request') request.get({ url: 'https://sandbox.api.high-mobility.com/v1/vehicle-data/autoapi-13/{vin}', headers: { Authorization: 'Bearer ' + accessToken } }, (error, response, body) => { console.log('error:', error) console.log('statusCode:', response && response.statusCode) console.log('body:', body) }) ```
{% hint style="info" %} **AUTO API** Check out the [Data API OpenAPI Specification](/api-references/data/vehicle-data) for all details {% endhint %} # MQTT V1 Use the MQTT Auto API broker to subscribe and stream live vehicle data updates over MQTT {% hint style="danger" %} This method is deprecated, please use [MQTT V2](/docs/vehicle-data/mqtt-v2) {% endhint %} The MQTT Auto API broker enables you to subscribe to vehicle data updates and get them pushed to your application using the [MQTT protocol](https://mqtt.org/). This tutorial will help you get started step by step. ### Introduction to MQTT [MQTT](https://mqtt.org/) is an asynchronous message protocol built on the publish/subscribe pattern. On the server side, there is a data broker that delivers messages to connected clients that have subscribed to receive updates. At its core, it enables you to: * Move from poll-based to push-based API usage. * Subscribe to any data updates for vehicles that you have access to through a single TCP/TLS connection. * Work with a well-established standard, MQTT, with excellent tools for all platforms and operating systems. * Continue to work with data payloads based on the Auto API JSON schema. * Provide advanced use-cases that rely on events and car data updates being streamed second-by-second. {% hint style="info" %} **ENDPOINT URL** The MQTT broker URL is `mqtt.high-mobility.com:8883` for live vehicle data. To consume data from a simulator, connect to the sandbox broker URL on `sandbox.mqtt.high-mobility.com:8883`. {% endhint %} ### Topic and message structure All messages that are published are divided into different topics. By looking at the topic structure you can determine the type of data that is being sent and for which vehicle. Here's an example of the JSON that would be sent for the odometer data: Topic: `live/level13/1FBBEDED80595912588FF4FF/VFXXXXXXXXXXXXXXX/diagnostics/get/odometer` ```json { "message_id": "B10BB67D6B4D2EBAB49FD3F81D41111C2AC0D6E0816DE47F87DCDD1388F3D911", "version":1, "vin": "VFXXXXXXXXXXXXXXX", "capability": "diagnostics", "property": "odometer", "data": { "diagnostics": { "odometer": { "data": { "unit": "kilometers", "value": 100 }, "timestamp": "2021-11-01T10:33:10.000Z" } } } } ``` #### Topic breakdwon ``` topic: {environment}/{auto_api_level}/{app_id}/ {vin}/{capability}/{action}/{property} breakdown: environment: - live # live vehicle data - sandbox # simulator vehicle data auto_api_level: level13 # latest version of the Auto API app_id: Your unique App ID e.g. 9FBBEDED80595912588FF4FF vin: Vehicle Identification Number capability: Auto API capability action: - get # data published by the vehicle - set # currently not supported property: Auto API property ``` #### 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 [Auto API JSON schema](https://github.com/highmobility/auto-api-json-schema). ``` { "message_id": {Unique Message ID: string}, "version": 1, "vin": {Vehicle Identification Number: string}, "capability": {Auto API Capability: string}, "property": {Auto API Property: 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 The authentication is done using Client Certificates. Visit application page at , go to Streaming section and enable and download MQTT Certificate. ### Connect Once you have your authentication credentials you can go ahead and connect to the MQTT broker on `mqtt.high-mobility.com:8883`. You can use any preferred MQTT client software or library to do this, just make sure to pass in the root certificate, client certificate and private key before connecting. The following example shows how the terminal tool `mosquitto_sub` is used to both connect and subscribe to all messages: ```bash mosquitto_sub --disable-clean-session \ --cafile root.pem \ --cert certificate.pem.crt \ --key private.pem.key \ -h mqtt.high-mobility.com \ -p 8883 \ -q 1 \ -t 'live/level13/1FBBEDED80595912588FF4FF/#' \ -i '75374841-d7a5-4db7-b9b5-8a5f60eed79d' ``` The following parameters are needed for the connection: * clientId: The Certificate ID that is listed in MQTT Certificates page. The Certificate ID is also included in the downloaded certificate file name. Example: "75374841-d7a5-4db7-b9b5-8a5f60eed79d" * cleanSession: Set to false if you wish to receive missed messages since the last connection * QoS: Set to 1 in order to guarantee that a message is delivered at least once {% hint style="info" %} Each client certificate can be used for one active connection. If multiple active clients are needed, it's possible to get several client certificates issued for a single App ID. {% endhint %} ### Subscribe Once you have connected, go ahead and subscribe to any topic path that matches your App ID. Here are a few common use-cases: * To subscribe to all data updates, pass in `live/level13/{app_id}/#`. The hashtag in the end is a wildcard for all topics underneath that path. Replace `live` with `sandbox` if you are working with the simulator. * To subscribe to only specific properties for all cars, pass in the plus sign as a wildcard to match any VIN. Here's an example of only subscribing to odometer data: `live/level13/{app_id}/+/diagnostics/get/odometer` In MQTT, `#` is used as a wildcard sign when it's at the end of the topic. When the wildcard is in the middle of the topic path, `+` should be used. {% hint style="info" %} **HEADS UP**\ It's only possible to subscribe to one topic. 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. {% 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 [OAuth2 Consent Flow](/docs/oauth-2.0) or the [Fleet Clearance](/docs/getting-started/fleet-clearance) guide depending on your specific application. # 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](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](/api-references/data/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} } ``` {% 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://docs.high-mobility.com/help-center/) * Currently you are not able to revoke client certificates, we are working on the implementation. {% endhint %} ### Connect {% 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 %} 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 `--` 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](/docs/getting-started/fleet-clearance) guide depending on your specific application. # AWS Kinesis Stream real-time vehicle data into your own Amazon Kinesis pipeline With [Amazon Kinesis](https://aws.amazon.com/kinesis/) integration enables you to direct data from your vehicles to your own Kinesis stream. This tutorial will help you get started step by step. ### Introduction to Kinesis Amazon Kinesis is a scalable, real-time data streaming service designed to handle large volumes of data generated by applications, devices, or events. It enables the collection, processing, and analysis of streaming data with low latency. It allows you to: * Move from batch-based to real-time, event-driven data processing. * Ingest, store, and analyze continuous streams of data through a fully managed service. * Process high-throughput data payloads from your vehicles. * Continue to work with data payloads based on the Auto API JSON schema. ### Message structure Here is the JSON format that is used for every message that is pushed to your stream. All `data` objects, that hold the specific car data payload, are formatted according to the [Streaming Schema V2](/api-references/data/streaming-schema-v2). A breakdown of each property is found in the [Auto API schema](https://github.com/highmobility/open-api-specifications/blob/main/json-schema/auto-api/0002/). ```json { "message_id": {Unique Message ID: string}, "application_id": "Application ID: string(uuid)", "version": 2, "vin": {Vehicle Identification Number: string}, "data": {Auto API Schema V2: objects} } ``` {% 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 %} Here's an example of the JSON that would be sent for the odometer data: ```json { "version": 2, "message_id": "B10BB67D6B4D2EBAB49FD3F81D41111C2AC0D6E0816DE47F87DCDD1388F3D911", "application_id": "969d8950-1ecb-10d5-be96-ff8dceed5317", "vin": "VFXXXXXXXXXXXXXXX", "data": { "diagnostics": { "odometer": [ { "data": { "value": 2050, "unit": "kilometers" }, "timestamp": "2021-10-06T13:59:25.648943Z" } ], "speed": [ { "data": { "value": 42, "unit": "kilometers_per_hour" }, "timestamp": "2021-10-06T13:59:25.648943Z" }, { "data": { "value": 55, "unit": "kilometers_per_hour" }, "timestamp": "2021-10-06T13:59:28.788943Z" } ] }, "race": { "vehicle_moving": [ { "data": "moving", "timestamp": "2021-10-06T13:59:25.648943Z" } ] } } } ``` ### Create a Kinesis Stream The first thing you will need to do is to create a Kinesis stream in your AWS account. If you have no AWS account, you can [sign up here](https://aws.amazon.com/resources/create-account/). Once logged in, follow these steps: 1. Choose "Amazon Kinesis" to open the specific service page. 2. Click the "Create data stream" button 3. Fill in a name of your data stream 4. All options on the kinesis creation page can remain as already selected by default 5. Click "Create stream" to finalise the creation Once you have created your kinesis stream, you will need to update it's permissions policy to allow us to stream data to it: 1. In the kinesis details page, click on the "Data stream sharing" tab 2. Scroll down to the "Resource policy" and click edit and enter the following JSON. {% hint style="info" %} **SANDBOX VS. LIVE** Just mind that you need to replace the `` placeholders with the name of the stream that you just created. The `` placeholder is set according to if you are configuring a sandbox application or live data application. {% endhint %} * Sandbox principal: `arn:aws:iam::238742147684:user/xv-janus-kinesis-sink-production-sandbox` * Live data principal: `arn:aws:iam::238742147684:user/xv-janus-kinesis-sink-production-live` ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "StreamWriteStatementID", "Effect": "Allow", "Principal": { "AWS": "" }, "Action": [ "kinesis:DescribeStreamSummary", "kinesis:ListShards", "kinesis:PutRecord", "kinesis:PutRecords" ], "Resource": "" } ] } ``` #### Enable Encryption it's a good practice to enable server-side encryption for your Kinesis stream. 1. Go to "Configuration" tab in your stream 2. Scroll down to reach "Encryption" section and click "Edit"
3. Enable encryption and choose "Use customer-manged CMK". I**t's important to create a dedicated key and only share it with with High Mobility's AWS Principle** \ ![](/files/hwVhTWEfgWYNIgjUf4CC) 4. Your key must have the following key policy:
```json { "Sid": "High Moblity Access to Kinesis's key", "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "kms:GenerateDataKey", "Resource": "" } ``` ### Configure Project In your project view, configure your app to push data to your Kinesis stream. In the High Mobility console: In your project view, configure your app to push data to your Kinesis stream. In the High Mobility console: 1. Select the project you have created. 2. Choose "API Certificates" then "Streaming" in the left menu section. 3. Choose "Amazon Kinesis" as your choice of push data delivery. 4. Click "Save and Update" 5. Enter the ARN of your Kinesis stream that you created in AWS and hit "Save". {% hint style="info" %} **DELIVERY METHOD** Note that you can only have one specific streaming data delivery methodat any point of time. {% endhint %} Once you have saved we will verify that the connection is working by storing a test message in your bucket. The shard ID and sequence ID will be listed for you to verify. Only if the test push succeeds will the Kinesis configuration be saved. ### Receiving data You will now get any new data being generated by your vehicles pushed to your stream. If you are working in the sandbox environment, you can easily try it out in the simulator by changing a few data properties. Just make sure your application has the permission to receive the specific data. \ 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](/docs/platform/console/getting-verified-for-production) guide. # AWS S3 Push vehicle data updates directly into your AWS S3 buckets for scalable storage and analysis. With the AWS S3 integration it's possible for you to get vehicle data updates pushed directly to your AWS S3 buckets. This tutorial will help you get started step by step. ### Introduction to AWS S3 [AWS S3](https://aws.amazon.com/s3/) is a versatile object storage service offered by Amazon Web Services. It's possible for you to manage data buckets in your own AWS account and then configuring your data applications in our console to push data to your buckets. Using this method for data delivery works for many use-cases: * When you want to collect data from your fleet evaluation purposes without any technical effort. * When you are using Big Data platforms that have existing plugins for AWS S3, buckets can serve as excellent middle steps in your data pipeline. * If you are scaling your data usage to very large fleets, S3 can keep up with large volumes of push data at a low computing cost. * When latency in the data delivery is not an issue. Efficiency is more important than real-time updates. * Continue to work with data payloads based on the Auto API JSON schema. ### File and object structure All messages that are published are divided into different topics. By looking at the topic structure you can determine the type of data that is being sent and for which vehicle. ``` s3_uri: s3:////////