Ecobee API Python SDK

This project provides a simple python interface to interact with the ecobee Web REST API.

Overview

It provides the following functionality

• Manage Tokens Operations like regestering and refreshing
• Format boilerplate api requests.
• Provide simple functions to perform common api operations

Install Guide

Before you begin Register as an ecobee Developer Here https://www.ecobee.com/developers/
Note: lines with $ mean execute this command in bash

Clone the Repository
$ git clone https://github.com/ecobee/python_api_sdk.git

Navigate inside the root directory
$ cd python_api_sdk

Install the Repository
$ pip install .

#Run the interactive enviornment setup note this only works for mac / linux
$ python setup_scripts/env_setup.py

User Guide

Note: Bolded Lines with >>> mean execute this command in python

Adding Users

>>> # Create an ApiInterface object
>>> from ebapi.api_interface import ApiInterface
>>> interface = ApiInterface()
>>> 
>>> #Add a user
>>> interface.add_user()
Enter the PIN '<4-digit-pin>' into the Add Application window and click Add Application<br>
waiting press enter to continue...
>>> 

Adding an 3rd Party Application

1. Navigate to www.ecobee.com and login with you username and password
2. My Account (Top right)
3. My Apps (Bottom Left)
4. Add application (Bottom Left)
5. Enter the <4-digit-pin> into the text box
6. Click Validate (Bottom Right)
7. Click Add Application

Return to you python session and press Enter
The SDK will have stored access and refresh tokens for the user accout
It will also store a all the thermostats that the user has

Making Requests

Requests are made by sepecifying a method of the ApiInterface Object
and a 12 digit Thermostat Identifier.
These can be found on the About My Thermostat (Bottom Right of a Thermostat Page)

All Requests Reutrn Dictionaries from the Ecobee API's JSON format.

Reference Documentation: https://www.ecobee.com/home/developer/api/introduction/index.shtml
Object Defitions: https://www.ecobee.com/home/developer/api/documentation/v1/auth/auth-intro.shtml

>>> # will dispay the Thermostat ID that are stored
>>> thermostat_identifier.show_users()
>>>
>>> #12 digit thermostat ID
>>> thermostat_identifier = "123456789012" 
>>> 
>>> # Return a Dictionary of the thermostats settings
>>> interface.get_settings(thermostat_identifier)
>>>