Occasionally I geek out on some of the more technical aspects of owning my Model S, and today is going to be one of those days. Read on if you’re interested in learning more about the undocumented application programming interface (API) to your Model S and Model X, and exploring its capabilities.
Tesla Mobile API
An API is a specification for programs to interact with one another through a piece of software. Whenever you’re dealing with connected devices, especially if they’re interacting over-the-air, they’re likely using APIs to communicate with one another. APIs come in a variety of types, each including its own security model that requires authentication before the API is useable. Security enforces that you are who you say you are, and that you’re allowed to use a set of features exposed through the interface.
Tesla’s iOS and Android mobile app for instance connects to a set of APIs that allows the app to communicate with your Tesla. Start the car, vent the sunroof, honk the horn, are just some of the features that get invoked via an API whenever a user taps a button on their mobile device. The car itself is also using one or more APIs to talk to Tesla to get software updates, send debugging information to Tesla, etc. Systems often have many APIs for different purposes.
The API we’re going to focus on is the one used by the mobile applications. This Mobile API is not documented by Tesla and is not intended to be used by anyone other than Tesla employees. You can use applications Tesla has created that use the API but you’re not supposed to make your own applications using the API.
Like many things these days, if it exists it can be figured out and some energetic Tesla owners have figured out how the API works. There’s a free site called Apiary that can be used for documenting APIs and that was used to document the Tesla Model S API.
Libraries
While the documentation will allow you to immediately start programming, assuming you have a knowledge of how to interact with APIs, some folks have created libraries in various programming languages to assist with the basics of interacting with the Tesla Mobile API. What language you choose to program in and whether you use a library is either defined by the needs of the project or the personal preference of the programmer.
For my hacking/playing around I use the Python programming language. Searching around I found a few Python libraries to make integrating to the Tesla Mobile API easier. The one that best suited me is Teslajson by Greg Glockner which is a small Python file containing all of the basics for interacting with the Tesla Mobile API. For those interested in libraries for other languages, I’ve found libraries for Java, Node, Ruby, and C#.
Python Code Sample
I won’t be going into all the API calls and how they work, but I’ve provided a quick minimal working example that you can use to follow along:
In the example above I’m using my email address and password to log into the Tesla server (same one I would use to access the MyTesla portal when ordering the car and browsing the Tesla forums), and I am getting a connection object. Then I use that connection object to request data about my car. I’ve named it “Baddog”. From that data I can extract the current odometer reading.
Running this little program simply shows my cars current mileage:
Note that there are various tricks to using APIs like this. You should keep the access token around to avoid having to re-authenticate each time and you should also handle API access errors.
So what can you do with it?
Third-party apps such as VisibleTesla, RemoteS, and of course our very own Tesla Lifestyle App (also on Android), use Tesla’s Mobile API in some shape or form to either control vehicle functions or access data provided by Tesla.
For myself I’ve done a few things:
- Automatically recording my daily driving data (miles driven, charge amount, etc)
(more on this in an upcoming data post). - Checking nightly if my Tesla is plugged in and email me if it isn’t.
- Automatically tweeting my daily mileage and efficiency.
- Automatically tweeting when I cross a 1,000 mile mark.
- Check for new API fields/data (as Tesla evolves the Mobile API) and emailing me when things change.
There are other things I have in mind like automatically closing the sunroof if it looks like its going to rain, checking my calendar and pre-heating/cooling the cabin based on the next appointment time, etc. You can also access the car’s location to track speed, places you’ve visited, and more – all great areas for experimentation. If you use the historical charge data, you could also implement the much-desired “set charge end time” feature which is on my short list to do when I have some time.
Summary
The Tesla Mobile API is undocumented and not officially supported by Tesla, but with some simple programming you can accomplish really cool things with it. Tesla understandably doesn’t have the resources to officially support this API right now, but it’s great to see that Tesla is not going out of their way to make it more difficult for people to use and experiment with it.
The programming interface gives you basic controls such as opening the sunroof and honking the horn, but vital driving functions such as steering, power, etc. are not accessible. I believe Tesla is watching what people develop using this API and will use that knowledge to enhance their mobile apps and vehicle features over time.
Now, go ahead and stretch your imagination to see what you can build.
