GET Thermostat Summary (Polling)

URL: /thermostatSummary

Accessible by: Smart, EMS, Utility accounts.

This request retrieves a list of thermostat configuration and state revisions. This request is a light-weight polling method which will only return the revision numbers for the significant portions of the thermostat data. It is the responsibility of the caller to store these revisions for future determination whether changes occurred at the next poll interval.

The intent is to permit the caller to determine whether a thermostat has changed since the last poll. Retrieval of a whole thermostat including runtime data is expensive and impractical for large amounts of thermostat such as a management set hierarchy, especially if nothing has changed. By storing the retrieved revisions, the caller may determine whether to get a thermostat and which sections of the thermostat should be retrieved.

Most revisions are UTC date/time stamps in the format: YYMMDDHHMMSS. However, due to possible time drift between the API consumer, the server and thermostat, it is recommended that they are treated as a string, rather than as a date/time stamp. The recommended method to test for revision changes is to simply do a string comparison on the previous and current revision. If the strings match, nothing changed. Otherwise request the thermostat including the relevant information which changed.

The Thermostat Summary can also return the current status of the equipment controlled by the Thermostat. The equipmentStatus data is returned as a CSV String. This CSV String will list all equipment which is currently running. If a specific equipment type is not returned in the CSV String then it is not running, or "OFF". To retrieve this data the Selection object specified in the request should have the includeEquipmentStatus flag set to true. The default is false.

IntervalRevision differs from RuntimeRevision in that the runtime revision is the revision of all the runtime information combined, whereas the interval revision only changes when the thermostat transmits its 15 minute interval status message to the server. Runtime revision will be updated when the thermostat sends the interval status message every 15 mins as well as whenever the equipment state changes on the thermostat, and it transmits that information. The equipment message can come at a frequency of 3 mins. When expecting only updates to the thermostat telemetry data, use the IntervalRevision

It is the responsibility of the caller to ensure that the sizes of the revisionList and statusList are parsed in a flexible manner, as additional revisions and statuses will be added with new features and functionality.

Request Properties

Property	Version	Type	Required	Description
selection	1	Selection	Yes	The selection criteria for update.

Response Properties

Property	Version	Type	Description
revisionList	1	CSV[]	The list of CSV revision values. See below.
thermostatCount	1	Integer	Number of thermostats listed in the Revision List.
statusList	1	CSV[]	The list of CSV status values. See below.
status	1	Status	The api response code.

CSV Revision Values

The revisionList property of the response contains a colon separated list of values (in order):

Value	Type	Description
Thermostat Identifier	String	The thermostat identifier.
Thermostat Name	String	The thermostat name, otherwise an empty field if one is not set.
Connected	Boolean	Whether the thermostat is currently connected to the ecobee servers.
Thermostat Revision	String	Current thermostat revision. This revision is incremented whenever the thermostat program, hvac mode, settings or configuration change. Changes to the following objects will update the thermostat revision: Settings, Program, Event, Device.
Alerts Revision.	String	Current revision of the thermostat alerts. This revision is incremented whenever a new Alert is issued or an Alert is modified (acknowledged or deferred).
Runtime Revision	String	The current revision of the thermostat runtime settings. This revision is incremented whenever the thermostat transmits a new status message, or updates the equipment state or Remote Sensor readings. The shortest interval this revision may change is 3 minutes.
Interval Revision	String	The current revision of the thermostat interval runtime settings. This revision is incremented whenever the thermostat transmits a new status message in the form of a Runtime object. The thermostat updates this on a 15 minute interval.

CSV Status Values

OPTIONAL - only returned when the request Selection object has the includeEquipmentStatus flag set to true. The statusList property of the response contains a colon separated list of values (in order):

Value	Type	Description
Thermostat Identifier	String	The thermostat identifier.
Equipment Status	String	If no equipment is currently running no data is returned. Possible values are: heatPump, heatPump2, heatPump3, compCool1, compCool2, auxHeat1, auxHeat2, auxHeat3, fan, humidifier, dehumidifier, ventilator, economizer, compHotWater, auxHotWater.

Example Request:

Request Body

NOTE: Request body is not encoded for example purposes.

                
HEADERS:
	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg
	
REQUEST:
	GET https://api.ecobee.com/1/thermostatSummary?json={"selection":{"selectionType":"registered","selectionMatch":""}}
				

Sample API Call

curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/thermostatSummary?json=\{"selection":\{"selectionType":"registered","selectionMatch":"","includeEquipmentStatus":true\}\}'
				

					
$.ajax({
    beforeSend: function(request) {
        request.setRequestHeader("Authorization", "Bearer ".concat(ACCESS_TOKEN));
    },
    dataType: "json",
    url: 'http://localhost:8080/home/api/1/thermostatSummary?json=\{"selection":\{"selectionType":"registered","selectionMatch":"","includeEquipmentStatus":true\}\}',
    success: function(data) {
    	var response = JSON.stringify(data, null, 4);
    }
});
				

Example Response:

    {
        "status": {
            "code": 0,
            "message": ""
        }
        "thermostatCount": 3,
        "revisionList": [
			"123456789101:MyStat:true:071223012334:080102000000:080102000000",
			"123456789102:Room12:true:071223012334:080102000000:080102000000",
			"123456789103::false:071223012334:080102000000:080102000000"
            ]
    }
    

Example Request with equipmentStatus data:

NOTE: Request body is not encoded for example purposes.

HEADERS:
	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg
	
REQUEST:
	GET https://api.ecobee.com/1/thermostatSummary?json={"selection":{"selectionType":"registered","selectionMatch":"","includeEquipmentStatus":true}}
				

Example Response with equipmentStatus data:

    {
        "status": {
            "code": 0,
            "message": ""
        }
        "thermostatCount": 3,
        "revisionList": [
            "123456789101:MyStat:true:071223012334:080102000000:080102000000:080102000000",
            "123456789102:Room12:true:071223012334:080102000000:080102000000:080102000000",
            "123456789103::false:071223012334:080102000000:080102000000:080102000000"
            ],
  		"statusList": [
			"123456789101:auxHeat1,compCool1",
			"123456789102:auxHeat3,ventilator,humidifier",
			"123456789103:"
  		]
    }
    

Back To Top