Get current mileage via Connected Car Data

‍
Most cars are equipped with in-vehicle telematics systems that make it simple to access live vehicle information on demand. Consequently, there is no longer additional hardware such as OBD2 dongles required in order to automatically update the odometer value in the respective backend systems. High Mobility provides a harmonised API that ensures that data is always delivered in the same structure and format no matter which cooperating car brand is used. Since our solution is also fully GDPR compliant, it simply paves the way for streamlined customer and driver onboardings. 

In this guide, we are demonstrating how you can access our most popular data point via High Mobility’s REST API by using the Postman tool as a common app for API testing. We assume that you already know how to create a free High Mobility account and how to set up your workspace with a data container. Additionally, we expect that the associated app has been  approved and that vehicles have been activated accordingly. If you have not yet gone through those steps we highly recommend reviewing our Open Dev Talks “How to get started with connected car data?” and “How to manage consent and connect fleet vehicles”. 

In order to start working with the REST API, we are recommending going through each of the following steps. Every underlying aspect will be explained in more detail both in the video of our 7th Open Dev Talk and this blog post.

• Setup Postman environment and collection
• Generating a Vehicle Access Token
• Retrieve odometer data via vehicle status endpoint
  ‍

Setting up and configure Postman

If you have not downloaded and worked with Postman before, please get the app from the official source and install it accordingly. In case you start testing in the Sandbox environment using our vehicle simulator, you can start to download the collection and environment directly from our platform. Go to high-mobility.com, login to your account and open the “Build” environment. Select your app container and retrieve the corresponding Postman config files directly from the Client certificate tab. Currently, this option is available for single driver apps and fleet support will be added in the near future as well. Alternatively, we are providing access to the corresponding Postman collection and environment for B2C and Fleet purposes via GitHub.

Next, open Postman and hit the Import button. Select both the environment and collection file and confirm via the “Import” button. As soon as the import has finished, you will see a long list of requests and endpoints on the left hand side.

The next step is to prepare the associated Environment. Click on “Environments” on the left navigation bar and you will see that the Environment for the High Mobility Sandbox has been already established with help of the import process. If you already start using real cars and the Production environment you can simply duplicate the Sandbox environment. Go to your app container and make sure that the APP_ID parameter has been set and that the value corresponds to the displayed value highlighted in the app container at the High Mobility platform. If it is not shown in the overview, please go ahead and add a new variable APP_ID and set the current value to the identifier listed in the header section of your app container. The variable REST_API_CONFIG should hold the full snippet listed under Client Certificates > REST API, the BASE_URL should correspond to the api_url value that can also be found in the REST API snippet. Make sure that the TOKEN_URI matches the associated value in the OAuth Client settings of you data container.

Generating the vehicle access token

When handing-in a vehicle for activation, you will receive an access token in return. This token can later be used to call the API and to retrieve car data such as the odometer. In our example, we follow the fleet clearance documentation to match our sample use case context.Alternatively, the B2C user consent flow can be reviewed over here.

As soon as your vehicle is activated you can use the ‘.../fleets/acces_tokens’ endpoint in order to retrieve an access token for your vehicle. This endpoint requires the vehicle identification number (VIN) of your targeted vehicle and your Auth Token as parameters. More details about generating the auth token can be found in our Open Dev Talk 5 session. The full sample request snippet is listed in our technical guide as well.

As soon as you execute the request you will receive an access token that can be used throughout its given lifetime. Additionally, the response will highlight the data points scope of your related data container and the refresh token which can be used to renew the access token. To finalise this step, you can simply copy and paste the access token to the corresponding field in the postman environment. Make sure to save changes before going to the next step.

Getting odometer data via REST API

In your collections overview on the left hand side of Postman you will notice that vehicle data items are packaged into endpoint categories. Since the odometer data is associated with our diagnostics category you can simply retrieve the data value via this endpoint. However, we usually recommend using the Get Vehicle Status Endpoint. This specific endpoint will return all available values according to your permitted and activated list of data points no matter the category.

As soon as you select the desired endpoint and hit “Send”, Postman will execute the request and display the result in the response view. Every response highlights the VIN and brand name as well as a list of data items accompanied by a timestamp (in UTC +0) in order to better understand when the data value has been generated in the vehicle. In our example, we can see a vehicle mileage of 6871 kilometers and based on the timestamp we can tell that the vehicle has not been driven for the past 2 days.

‍

-------------------------------
High Mobility Open Dev Talks 

At High Mobility, we are passionate about new technology. We offer free open source tools and developer friendly documentation for any projects to be integrated smoothly. More than 800 developers and product managers have already signed up for our moderated community platform and we are hosting connected car competitions for your innovative, connected car ideas. 

In our free monthly, 30-minute Open Dev Talk online session we are explaining exciting connected car related topics in 15 minutes and dedicate the rest of the time to your questions and ideas.

Join our community on Slack