Tags
Occasionally I geek out on one 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 the undocumented software interface to your Model S and Model X and the capabilities of the Tesla Mobile API.
The Mobile API
API means Application Programming Interface. Its a specification for how programmers can interact with another piece of software. Whenever you have connected devices they’re using APIs to communicate with other computers. These APIs come in all shapes and sizes. Security adds another level of complexity with different authentication methods for proving you are who you say you are and that you’re allowed to use the API.
In the case of Tesla, the Tesla Mobile apps on iOS and Android use an API to communicate to Tesla to allow you to start your car, vent the sunroof, etc. 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. This specification provides what most programmers would need to successfully write an application that uses the API.
Libraries
While the API documentation is sufficient to get started programming, some of the basics you would be doing as a programmer are a bit like re-inventing the wheel. Some people 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 or not is either defined by the needs of the project or the personal preferences of the programmer.
For my hacking/playing around I use the Python programming language. Searching around found a few Python libraries to make integrating to the Tesla Mobile API easier. The one I found that was the best fit for me was Teslajson by Greg Glockner which is a single small Python file containing the basics. For those interested in libraries for other languages i’ve seen libraries in Java, Node, Ruby, and C# among others.
Basic Use
I won’t be going into all the API calls and how they work but here’s a quick minimal working example:
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 MyTesla or 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 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, you should handle API access errors, etc.
So what can you do with it?
There are large examples like VisibleTesla, RemoteS, and ConnecTT which are full blown free or for-pay applications that use the API to control or monitor your car.
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 cars’ location to track things like speed, places you’ve visited etc so that is another area 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 some cool things with it. Tesla understandably doesn’t have the resources to officially support this API right now, but its great to see that Tesla is not going out of their way to make it more difficult for people to use and experiment with.
While this is a programming interface and you could do odd things like open the sunroof or honk the horn at the wrong time, but you can’t control steering, power, etc so it is a pretty safe API to have available. I believe Tesla is watching what people develop using this API and will use that knowledge to enhance their mobile apps or features in their cars over time.
What would you do with access to the API? Leave your thoughts in the comments below.
The task I would most like to do is to adjust the climate control settings. It would be helpful to be able to turn on the A/C (or turn it off), change the air flow, and so on.
I also like your ability to download daily data on travel and energy consumed.
Interesting. How/when would you adjust those?
Since I am retired and have an irregular travel schedule, I can easily imagine wanting to change the climate control settings for preheating or cooling if I have not been in the car for a few hours.
Generally, I like to leave A/C off to save energy. It seems to make a noticeable difference, and seems to be on by default, even in cool weather. (I have had other cars like that, too, so it is not unique to Tesla.) But it would be nice to be able to turn it on for preheating or precooling when there was humidity or more outside heat than when you parked the car. Or to turn it off when you know it was on the last time you shut down the car.
Also, the air could be directed to the windshield when there is frost on the glass so the windshield would be more likely to be clear when you got into the car.
Ideally, one would be able to activate the defrost mode with full fan, full AC. And maybe the rear defroster, too, if that control is in the API.
Interesting. You can set the temperature on each side individually and turn the whole A/C/heat unit on/off. When you turn it on it only remains on for 15 minutes. You cannot control Smart Preconditioning via the API and you can’t control the A/C mode (windshield only vs floor and windshield). You can’t control defrosters at all.
Once you turn A/C off it remains off until you turn it on specifically with the API or turn it back on manually when you get back into the car. It doesnt go back into the “on but not running” state so that makes for some tricky logic.
The API is pretty limited in what you can do and is mostly just what you can do in the official Tesla app with the one exception of being able to open the sunroof fully via API.
Hmm. I thought the heat would stay on for 30 minutes, glad to learn it is only 15. Still think it would be useful to be able to switch the A/C on or off, despite the limitations. But I won’t hold my breath, given the challenges!
Love the Tweet process. Have you though about packaging this up for non-programmer owners? Your example of daily usage is great for a long-term record. Are you keeping this data in a table as well to summarize over time versus just tweets/emails?
Ive been wanting to open source some of this work for a while but just haven’t had the time.
I do keep all the historical data and more. Right now its not a DB but a JSON file but it would allow historical reporting etc.
>> Check for new API fields/data
How are you doing this? I see that you have open-sourced some of your code, but don’t see this particular part. When I compare the API doc on Apiary to some of the features I see in apps like Remote S, it appears that Apiary must be out of date or incomplete? I’d like to set the max charging amps via the API, but don’t see a way to do that.
The Apiary docs are out of date in the examples/output they show but not in the basics of how to authenticate, get data etc.
For the fields I detect, I just keep a list of all fields seen before with the queries and then get all the fields again and look for new ones. That’s automated of course, but not difficult.