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.

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.

API USAGE LIMITS

  • DO NOT poll at an interval quicker than once every 3 minutes, which is the shortest interval at which data might change.
  • DO NOT have more than 2-3 open HTTP requests with the ecobee API at any given time; wait until the ecobee server has responded before issuing additional API requests.
  • If you are a Utility or EMS account and you are using management sets as your selection target, DO NOT have more than 1 open HTTP request with the ecobee API at any given time; wait until the ecobee server has responded before issuing additional API requests.

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

Show code sample in:
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\}\}'
				

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