TeslaJS

An unofficial NodeJS library that encapsulates the Tesla RESTful API.

Note: If you are planning to purchase a Tesla you can get 1,000 miles of free supercharging using this referral link.

This library currently supports all existing Tesla vehicles.

First, it is important to acknowledge that there are already several very good Javascript libraries available for the Tesla. So why create another one? Rather than contribute to or modify one or more of the existing libraries, this library was created for two main reasons:

1. The anticipated need for a few small but important features that existing libraries did not provide
2. I was looking for a personal opportunity to learn more about the Tesla REST API, NodeJS, Express and Git/GitHub

Notable Features

With the introduction of the new OAuth-based owner API, one of the features I wanted was the ability to make API calls without having to login each time a new process was invoked. Many existing libraries require a login transaction with each initiation of the library. With the TeslaJS library, once an auth token is retrieved it can be cached and used to make other Tesla REST API calls. For certain use cases, notably server logging of multiple vehicles, this can be important for moderating load on the Tesla login servers.

This is also important if you want to use the library to do server-based data logging. It is generally safer to store an OAuth token on the server rather than logon credentials. If the server is compromised only the OAuth token is at risk and all existing tokens can be invalidated by changing the password on the account.

Another feature that I wanted was API stateless-ness (achieved via an options parameter to API calls) so that it was possible to use the library to make multiple overlapping async calls for different vehicles for data-logging.

What's New!

You can read the complete history of changes in the CHANGELOG.

Here are some of the more recent features and fixes:

1. In V4.10.0 merged #275 to fix #273, added new endpoints, bug fixes
2. In V4.9.8 updated for latest changes to Tesla auth flow
3. In V4.9.4 fixed #210 streaming update to oauth
4. In V4.9.3 fixed #188 incorrect VIN for post 2018 cars
5. In V4.9.2 merged PR #191 added exports.promises object avoiding Async suffixes

Migrating Major Version Changes

You can find instructions on how to migrate across major version changes by reading the MIGRATION guide.

Known Issues

1. The homelink API appears to require Autopilot hardware. Can someone with AP test and report back?
2. Calendar support not yet functional. If someone can share the JSON for a valid calendar request that would help!

Library Users

A growing number of projects use the library or are based on its code, examples:

• Tesla Control app in the Windows Store. This Universal Windows App runs on Windows desktop, Windows Phone and Xbox.
• Nikola app on Github. This is a cross-platform app built with Electron, currently available for macOS and Windows.

Project Principles

This project has a few principles that have and will continue to guide its development.

1. Dependency lean. Try to keep the required dependencies to a minimum.
2. Comprehensive. Attempt to expose the full Tesla REST API surface area.
3. Simple. Using the library should be simple and straightforward following common conventions.
4. Server friendly. Provide for use based on auth tokens and avoid requiring access to passwords.

Documentation

We've recently added auto-generated documentation via jsdocs. See the DOCS for a mostly complete reference. Please let us know if you see something missing and we will continue to expand.

Contributing

Contributions are welcome, particularly bug fixes and enhancements! Refer to our Contribution Guidelines for details.

Please note that Project owners reserve the right to accept or reject any PR for any reason.

Code of Conduct

Before contributing or participating in the TeslaJS community please be sure to familiarize yourself with our project CODE OF CONDUCT. These guidelines are intended to govern interactions with and within the TeslaJS community.

Tesla API Documentation

The Tesla REST API encapsulated by this library was documented through the collaboration of many Tesla owners. Please thank and support them for their continued efforts! The latest REST API documentation can be found here

Warranty Disclaimer

You may use this library with the understanding that doing so is AT YOUR OWN RISK. No warranty, express or implied, is made with regards to the fitness or safety of this code for any purpose. If you use this library to query or change settings of your vehicle you understand that it is possible to make changes that could inadvertently lower the security of your vehicle, or cause damage, through actions including but not limited to:

• Unlocking the vehicle
• Remotely starting the vehicle
• Opening the sunroof
• Opening the frunk or trunk
• Lowering the battery charge level
• Impacting the long-term health of your battery

Please be careful not to use this code in a way that loads the Tesla servers with too many concurrent requests. Calling the Tesla REST APIs at a very high frequency will stress the Tesla servers and could get your IP or favorite cloud service blocked by Tesla. Or in the worst case it could cause Tesla to revoke the key that enables access via this and many other libraries.

Installation

In order to use the library and/or samples you must first download and install NodeJS. An installable TeslaJS module for npm is now available.

To download and install the library and all of its dependencies to a local project directory use the following:

npm install teslajs

If you prefer to download and install the library globally for all future node projects you may use:

npm install -g teslajs

You may also install directly from the GitHub source. Either download and unzip the source, or clone the repository.

Remember, whether you install via ZIP source or Git clone you must install the dependencies before using TeslaJS.

To install dependencies via npm, from the root level of the library directory type:

npm install

This library and its accomanying samples are under active development. New features, samples and bug fixes are being added regularly. To ensure that you have the very latest version of TeslaJS and it's dependencies be sure to update frequently.

To do so, from your project directory type:

npm update

Library Usage Examples

Login Example

As you can see below, it is very simple to login and acquire an OAuth token.

    var tjs = require('teslajs');

    var username = "<your MyTesla email>";
    var password = "<your MyTesla password>";
    var mfaPassCode = "<your MFA passcode, if applicable>";

    tjs.login({
        username: username,
        password: password,
        mfaPassCode: mfaPassCode
    }, function(err, result) {
        if (result.error) {
          console.log(JSON.stringify(result.error));
          process.exit(1);
        }

        var token = JSON.stringify(result.authToken);

        if (token)
            console.log("Login Succesful!");
    });

Note: Currently the only way to invalidate an issued token is to change your MyTesla account password. Therefore, you must take care to properly secure tokens. Do not share them over an unsecure connection, or store them on a public machine.

Vehicle Example

With the OAuth token from a successful login() API call you can query the vehicle for the account:

    var options = { authToken: result.authToken };
    tjs.vehicle(options, function (err, vehicle) {
        console.log("Vehicle " + vehicle.vin + " is: " + vehicle.state);
    });

Or using the Async Promise-based calls:

    tjs.vehicleAsync(options).done(function(vehicle) {
        console.log("Vehicle " + vehicle.vin + " is: " + vehicle.state);
    });

Charge State Example

Adding the vehicle ID from a successful vehicle() API call to options you can make other Tesla REST calls:

    var options = { authToken: result.authToken, vehicleID: vehicle.id_s };
    tjs.chargeState(options, function (err, chargeState) {
        console.log("Current charge level: " + chargeState.battery_level + '%');
    });

And using the Async Promise-based