Core Concepts

The following introduces the core concepts regarding ecobee thermostats.

API Versions and URLs

The ecobee API requires an explicitly specified version number in all request URLs. This explicit API version number ensures that the caller makes requests to the appropriate version of the API and that future changes in the API do not impact the caller's code. A prime goal of the ecobee API is to always be backward compatible within a specific version.

The API version may increase if changes added to the API are no longer compatible with the previous versions of the API. This may be the structure of data objects, removal of fields or other drastic and disruptive changes. The API version is not expected to change if new fields are added to objects.

It is the responsibility of the API consumer to ensure that the addition of fields to the JSON representation of objects is properly handled by the callers deserialization implementation.

The base URL format for making API calls follows this convention:

https://api.ecobee.com/{version}/{requestURL}

Example:

https://api.ecobee.com/1/summary?token=...

The following base URLs are used to access the API:

Version Production Server URL Beta/Test Server URL
1 https://api.ecobee.com/1 https://beta.ecobee.com/home/api/1

Note that you must use HTTPS to make API requests, HTTP is not supported and your client will be redirected to the HTTPS URL. Most HTTP client implementations do not support redirection by default if at all.

Thermostat Models

The ecobee API currently supports two thermostat products:

Smart: The smart thermostat is a product geared for the home user.

EMS: The EMS (Energy Management System) thermostat is a product geared for commercial user and management companies who wish to monitor and manage many thermostats across multiple locations from the same management portal.

The type of thermostat may be read from the thermostat property modelNumber. The following values are supported:

modelNumber Value Thermostat Model
idtSmart The ecobee Smart model.
idtEms The ecobee Smart EMS model.
siSmart The ecobee Si Smart model.
siEms The ecobee Si EMS model.
athenaSmart The ecobee3 Smart model.
athenaEms The ecobee3 EMS model.
corSmart The Carrier or Bryant Cor model.
nikeSmart The ecobee3 lite Smart model.
nikeEms The ecobee3 lite EMS model.

Thermostat Brands and Features

Every thermostat has a single brand and additionally, can have any number of features associated with it. Both these properties are part of the Thermostat object. The features property is represented by comma-separated text for thermostat's with more than one feature.

Brands we currently support can be seen below.

  • ecobee
  • Bryant
  • Daikin
  • ClimateMaster
  • Carrier

Similarly, features we currently support are listed below.

  • HomeKit
  • ClimateTalk
  • Serial Communicating

Account Types

Some features of the API may be available to only specific account types. For the Smart and EMS account, the appropriate model of the ecobee thermostat is required in order to utilize that account. For Utility, either type of thermostat is supported. This is indicated where appropriate.

The following account types currently exist:

Smart: A Smart account is a residential thermostat user account which includes Smart, Si, ecobee3, ecobee3 lite, Carrier and Byrant thermostat types. This account is typically associated with a home owner with one or more thermostats registered to the same account.

EMS: An ecobee Energy Management System (EMS) account is a commercial management company which has deployed a number of EMS thermostats and wishes to manage them from a central location. EMS accounts have one or more EMS model thermostats registered.

Utility: A special account type for large utilities who do not directly control thermostats, but may issue requests to reduce load on their power grid. Utility accounts may have Smart or EMS model thermostats registered with the utility. Thermostats registered to a utility are still registered to a user account which is Smart or EMS.

Note: The Utility users are restricted to only have GET (or view) access to certain properties of the Thermostat object in order to protect the Thermostat owner's private information. For the list of include* properties refer to the Selection object.

Management Set Hierarchy

For EMS and Utility account types only:

To associate thermostats to an EMS or Utility, a web-based portal is created for the company. Thermostats must be added to a portal first before they can be addressed by the ecobee API with the privileges granted to the EMS or Utility account type. Thermostats associated with a company portal can be organized into folder-like groupings called a management set.

When an API endpoint allows for a selectionType target of managementSet, the name of the management set can be used to address a large number of thermostats in a single API request.

For more information about using management sets and organizing thermostats into a hierarchy through the API, refer to Getting Started with Management Set Hierarchy.

Communication with the Thermostat

The following simplified diagram summarizes the flow of data between all ecobee network components.

communication flow diagram

All thermostats maintain a connection to the ecobee server which we call the communicator. The web server hosts both the user portal and the API servlets. The communicator and web server access a shared database store. When a request from the API is made, it is processed by the web server and transformed into a request that the thermostat can understand. It is then passed onto the communicator to which the thermostat is currently connected to. The communicator then routes the request to the thermostat. If the thermostat is currently not connected, its configuration is modified in the database and it will be merged by the thermostat when it reconnects to the server.

Due to the highly asynchronous nature of the thermostat/communicator/web server communication, the request to the API caller may return before the thermostat has received and processed the request. The caller should not expect that the request has been processed immediately. The API performs all possible validation before returning to the caller. Any validation errors will be indicated in the error response. The communicator will process the request as quick as possible, but due to network latency and server load, the request may take up to a few seconds to be fully processed. The delay may be greater if a very large number of thermostats is being modified at one time. The time for each thermostat to become updated becomes variable due to internal queueing and network latency.

By requesting the thermostat revision list and comparing it against the revision received during the call prior to the update is a good way of determining whether all thermostats had been updated. It is also safe to assume that the update is guaranteed to be received by the thermostat whether it is online or offline.

Values and Representation

The following is an explanation of various types of values and their representation within the API.

Temperature

Temperature values are expressed as degrees Fahrenheit, multiplied by 10. For example, a temperature of 72F would be expressed as the value 720. If the user preferences indicate the use of Celsius values, it is the responsibility of the caller to convert values to and from Celsius.

Where specified explicitly Degrees F indicates that the temperature will be returned in degrees Fahrenheit accurate to one decimal place (i.e. 18.5F).

Unknown Values

Numeric values whose value is not known are expressed as -5002. This is the numeric equivalent to a null value. The value of -5002 had been chosen as an unknown value because the representation of -500.2F is below absolute zero when representing temperatures.

Calibration Values

In some cases a sensor requires time to calibrate before it can provide accurate measurements. The value of -5003 had been chosen to represent the state and make it different from "Unknown" value.

Date and Time

The ecobee servers store dates and times in UTC (GMT timezone). The API also expects that all non-thermostat dates and times to be in UTC. Thermostat object dates and times are in device time (see below). UTC date/time is not affected by daylight savings time. It is the responsibility of the caller to convert dates and times as appropriate for display, including compensating for daylight savings.

There is a concept of dates "before time began" which is equivalent to a NULL time and "end of time" which represents infinite durations (i.e. events). The API represents these as:

Before Time Began Date: 2008-01-02

End of Time Date: 2035-01-01

Dates are formatted as: YYYY-MM-DD
Example: 2010-11-16

Times are in a 24-hour format: HH:MM:SS
Example: 13:42:15

DateTimes are in a combined format: YYYY-MM-DD HH:MM:SS
Example: 2010-11-16 13:14:15

Unless explicitly specified, dates and times can be assumed to be in UTC.

Device Time

The thermostat device maintains its own time which it synchronizes with the server during updates. The thermostat device time will be in the appropriate time zone, as specified by the thermostat owner. The dates and times sent by the thermostat are converted to UTC for storage. The thermostat contains information as to its offset in minutes from the GMT timezone. For example, a thermostat located in the EST timezone (-5 hours from GMT) would contain a value of -300.

During daylight savings time, the caller should check whether the thermostat settings indicate whether daylight savings is enabled. If daylight savings is enabled, modify the thermostat time accordingly after timezone conversion occurs.

Thermostat Events

Thermostat events are temporary modifications to the thermostat program. Events are defined by a start and end time, as well as additional information on how to modify the running program for the duration of an event. The events are managed as a stack, meaning that the first event is the currently active or the next event to become active in the future. Events are sorted by the start date/time.

Example:

An example of event stacking could be a thermostat in a hold event (1) which enters a demand response event (2) sometime later. The demand response event may be a relative modification to the set temperature. The user may once again set a favourable hold for the demand response event (3). The event stack would be: hold, demand response, hold.

Event Stack Example (by start date/time):

event stack example diagram

Scenario 1: Resuming an optional demand response.

Resuming the program would now remove the hold (3), making the demand response event the active event. The user would then be able to resume once more and remove the demand response (2), dropping back into the original hold (1).

Scenario 2: Mandatory demand response.

Providing that the demand response event (2) is mandatory, it would run its course and the user would be dropped back into their original hold. The user could still create the favourable hold (3) and resuming it would only resume to the demand response event. The user could not cancel the demand response event and must wait until it has run its course. If the favourable hold (3) had not been cancelled by the user, when the demand response event (2) ended, both it and the hold (3) would be removed. Leaving the thermostat in the original hold (1).

Scenario 3: Mandatory demand response and expired hold duration.

If the initial hold event (1) was for 2 hours and the demand response (2) started later, also for 2 hours, when the demand response ended all the events would be removed since all of their end times had expired. The thermostat would be then running its regular program.

Event Types:

Event Description
Hold A hold event is a user initiated override of the program. The user is able to set the thermostat temperature for a set period or indefinitely. The hold event takes effect immediately. If the hold is temporary, it is removed once the hold time expires. A new hold will replace an existing hold, unless they are separated by a Demand Response event or a Sensor Action event. See the Event Object definition for details on hold duration options.
Vacation A vacation event is a program override with a specific start and end time. A vacation may be created for a period in the future and contains the program override parameters. There may be any number of pending vacation events.
Demand Response A demand response event is an event generated by a utility requesting a reduction in energy consumption. A demand response event can only be generated by an utility account. Demand response events may be optional or mandatory.
Sensor Action Sensor actions are created when a configured action for a sensor event fires. These actions cannot be created or removed and are mandatory.

Optional events may be cancelled by the user, mandatory events cannot and must run their course. In the case of demand response, mandatory events created by a utility may be cancelled by the utility. They cannot, however be cancelled by a user.

Thermostat Program

The thermostat program is represented by a grid of weekdays by each 30 minute interval in a 24 hour period. Each 30 minute interval may be assigned a Climate. Climates are user defined, though ecobee provides 3 default climates (Sleep, Work, Home). Each climate defines the runtime configuration of the thermostat (i.e. heat/cool temperature, fan mode, etc.).

The API accessible program models the program accessible through the thermostat and web interfaces. An example of a simplified program is below.

DAY/TIME Sun Mon Tue Wed Thu Fri Sat
00:00:00 sleep sleep sleep sleep sleep sleep sleep
00:30:00 sleep sleep sleep sleep sleep sleep sleep
...               
08:00:00 sleep awake awake awake awake awake sleep
08:30:00 sleep awake awake awake awake awake sleep
09:00:00 sleep awake awake awake awake awake sleep
09:30:00 awake awake awake awake awake awake awake
...               
17:00:00 home work work work work work home
17:30:00 home work work work work work home
18:00:00 home home home home home home home
...               
23:00:00 home sleep sleep sleep sleep sleep home
23:30:00 sleep sleep sleep sleep sleep sleep sleep

Each of the climates: sleep, awake, work, home define the thermostat program settings for heat, cool and fan settings. Modification of a climate settings will result in all the time periods with that climate to be instantly changed.

Updates to a Program are atomic. The entire Program is expected in the request and it is either updated or it fails. Programs updated through the API are validated as follows:

  • None of the default climates may be deleted. Trying to do so will return an error.
  • A schedule cannot reference a non-existent climate. Deleting a climate and not deleting references to that climate in the schedule will return a validation error.
  • A climate does not have to be referenced by the schedule to be valid.
  • The climateRef cannot be modified for the default climates. Trying to do will return an error.

    • Additional climates may be created by the user. There is no limit to the number of climates which may be created.

    Thermostat Interval Report Data

    The interval report data contains thermostat recorded runtime information over a period of time. A thermostat posts its runtime information to the server every 15 minutes. This information contains 3 samples representing 5 minute intervals each. Over the course of a day, 288 samples are collected for the day (288 * 5 minutes = 24 hours). This information must be requested separately and is not included in the GET Thermostat request. The GET Interval Report request will retrieve this data for a specified period.

    It is important not to confuse the interval report data with the runtime data contained in the Thermostat object. The thermostat Runtime object represents only the last posted runtime state by the thermostat and does not contain the level of detail the interval report does and its time granularity is 15 minutes.

    Back To Top