Using HIGH MOBILITY’s Auto APIs: “Overall” Category
Following on from our last blog post which demonstrated how to connect to and use the HIGH MOBILITY Car Emulator, in this new series we’d like to introduce you to the Auto APIs available in our Developer Center.
Quick note: To make the most out of this post, please ensure you have created a login on the site.
In each post we’ll be covering:
- the general categories each API falls into
- the specifications of each API
- what kind of data each API can provide
- examples of apps you can build yourself.
We’ll be working through our Auto API Guide in the same order as it’s listed in the Developer Center, focusing on one API category per blog post. Today’s category is Overall but will also include a short introduction to the Auto API Guide itself and finish with a note about Failure Messages.
(In need of a visual demonstration? Check out this excellent high-definition webinar by HIGH MOBILITY founder Kevin Valdek covering these points.)
The Auto API Guide
To access the full list of APIs, your first port of call is the Auto API Guide, which is located in the HIGH MOBILITY Developer Center (you will need to make sure you are registered before you are able to access this part of the site). To find it from the main Developer Center landing page, simply click on Tutorials in the left-hand column. Underneath Getting Started you will see Possibilities Exploring, and then Auto API Guide. Click on the Auto API Guide link to see the list itself. You’ll notice that each of the APIs are separated into different categories, for example “Diagnostic”, “Chassis”, “Head Unit”, “Parking” and so on.
However, to get a more complete picture of the APIs, a good place to explore is the Car Emulator. To find the Car Emulator, click on the Develop tab at the top of the page. It is the tab with the tool icon on it. Now, click on the image of the car in the center of the page, and the emulator will open up.
Here you will see a list of the APIs under Capabilities on the right-hand side of the page. However, you might notice that a couple of APIs from the list in the Auto API Guide are not actually visible in this list on the car emulator page. The two “missing” APIs are Vehicle Status and Capabilities, both of which belong to the Overall category. Let’s take a look at these two APIs in a little more detail.
Capabilities API (Overall Category)
Return to the Auto API Guide in the Developer Center (under the Documents tab which we located at the start of this blog post). Under What’s on offer you’ll see the list of APIs. Capabilities is the first one on the list, belonging to the category Overall. Click on Capabilities.
What does this API do?
Using the Capabilities API, you are able to see which APIs your car model is able to support. Put simply, the function of the Capabilities API is to tell you what you can and cannot do with your car, by way of letting you know which APIs are compatible with your car model and which aren’t. As you may already know, these capabilities vary from model to model which is why the Get Capabilities function is so useful.
When you run the Get Capabilites function, the car will inform your device of which APIs it is able to support via a message to your device.
Please note: It’s good practice when you’re building an app which utilizes a lot of APIs to run Get Capabilities as standard.
On the same page, under Message Specification, you will see first the action for sending a request to run Get Capabilities, and further down a response outlining which APIs this car model can support. In this response you will see a list of links with all of the different capabilities. If you then click on a capability’s link, e.g Door Locks Capability, you’ll be able to see if it’s available or unavailable. Based on this information you know exactly what information you can show in your application.
Vehicle Status (Overall Category)
Return again to the Auto API Guide containing the list of all the APIs. Second on the list you will find Vehicle Status. When the car receives a Get Vehicle Status request from your device, the device receives a message response. This response contains some static information which doesn’t change (for example the unique Vehicle Identification Number, model name and licence plate) as well as dynamic information (information which can change depending on the status of the vehicle.) The dynamic information appears below the static information in the form of links and will include things like Engine State and Climate State which are able to tell you the current state of these elements of the vehicle.
If you have an API that only uses one vehicle state, it probably won’t make sense for you to have the Vehicle Status API, you can simply run the individual API to find out its current status. However, if you’re using a few APIs which use vehicle status information it might make sense to run Get Vehicle Status so you can evaluate the status of each element at once rather than calling up all the states individually. Doing so would almost certainly save you time.
Now that we’ve covered today’s two APIs from the Overall category, it’s time to take a quick look at Failure Messages; what they look like and, more importantly, the reasons they are most likely to appear. If you look to the list on the left-hand side of your current screen, you’ll see a subheader titled Failure Message (beneath Permissions). Click on this subheader. When a command you’ve sent to the emulator has not been successful you will get a failure message. There can be numerous reasons for a command not functioning as it should, with some of the most common failure messages listed in the screengrab below:
We’ve come to the end of today’s look at the Auto API Guide. In our next post in this series we’ll be examining the categories Diagnostics & Maintenance. We’ll be going through the APIs in these categories, their functions and how they can be used.
We hope you’ve enjoyed today’s breakdown. If you have any questions, please do reach out to us using the comments below. We’ll be happy to help you.
To stay ahead of all our news, updates, blogs and tutorials, make sure to connect with us via the HIGH MOBILITY Facebook page, Twitter or LinkedIn. You can of course also keep checking back to our Medium site, too!
Until next time, happy building.