Previous Example
Example 11: Changing your thermostat's program
Note on token authentication:
If you have completed the authentication process from Example 1, your access token will be pre-populated in all requests throughout every example.
To specify a different access token, please paste it in the form below and press 'Update'. Alternatively, you can go back to the first example here to re-authenticate. Doing either will save your access token for all future examples.
As explained in this example, a Program is a combination of a weekly schedule coupled with a list of possible Climate objects.
You can retrieve the program by using the following request.
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/thermostat?format=json&body=\{"selection":\{"selectionType":"registered","selectionMatch":"","includeProgram":true\}\}'
The resulting program property of the thermostat contains a schedule and climates. The schedule is an array of 7 elements. Each element represents a day within the week starting with Monday. Each day is split into 48 thirty minutes slots. Each slot is a string reference to a climate. The climates property is an array of possible Climate objects, which holds the appropriate, desirable comfort settings of the thermostat. The thermostat has three default climates, which are away, home, and sleep. Below is an excerpt of the full program, but you can download the full JSON program response here.
{
"page": {
"page": 1,
"totalPages": 1,
"pageSize": 1,
"total": 1
},
"thermostatList": [
{
"identifier": "318324666667",
"name": "Main Floor",
"thermostatRev": "150213203947",
"isRegistered": true,
"modelNumber": "athenaSmart",
"lastModified": "2015-02-13 20:39:47",
"thermostatTime": "2015-02-17 09:08:49",
"utcTime": "2015-02-17 14:08:49",
"program": {
"schedule": [
[
"sleep",
"sleep",
...snipped...
"home",
"sleep"
],
[
"sleep",
"sleep",
...snipped...
"home",
"sleep"
],
[
"sleep",
"sleep",
...snipped...
"home",
"sleep"
],
[
"sleep",
"sleep",
...snipped...
"home",
"sleep"
],
[
"sleep",
"sleep",
...snipped...
"home",
"sleep"
],
[
"sleep",
"sleep",
...snipped...
"home",
"sleep"
],
[
"sleep",
"sleep",
...snipped...
"home",
"sleep"
]
],
"climates": [
{
"name": "Away",
"climateRef": "away",
"isOccupied": false,
"isOptimized": true,
"coolFan": "auto",
"heatFan": "auto",
"vent": "off",
"ventilatorMinOnTime": 20,
"owner": "system",
"type": "program",
"colour": 9021815,
"coolTemp": 788,
"heatTemp": 608
},
{
"name": "Home",
"climateRef": "home",
"isOccupied": true,
"isOptimized": false,
"coolFan": "auto",
"heatFan": "auto",
"vent": "off",
"ventilatorMinOnTime": 20,
"owner": "system",
"type": "program",
"colour": 13560055,
"coolTemp": 734,
"heatTemp": 707
},
{
"name": "Sleep",
"climateRef": "sleep",
"isOccupied": true,
"isOptimized": false,
"coolFan": "auto",
"heatFan": "auto",
"vent": "off",
"ventilatorMinOnTime": 20,
"owner": "system",
"type": "program",
"colour": 2179683,
"coolTemp": 752,
"heatTemp": 662
}
],
"currentClimateRef": "home"
}
}
],
"status": {
"code": 0,
"message": ""
}
}
To make a program change, we will have to specify the entire program structure, and use the POST Update Thermostats method. Let us begin by creating the following new_pgm.txt file. Below is an excerpt of the file. Please download the entirety of the file before you execute the following the cURL command.
{
"selection": {
"selectionType":"registered",
"selectionMatch":""
},
"thermostat": {
"program": {
"schedule": [
[
"sleep",
"sleep",
"sleep",
"sleep",
"sleep",
"sleep",
"sleep",
"sleep",
"home",
"home",
"home",
"sleep",
"sleep",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"home",
"sleep"
],
...snipped...
[
"sleep",
"sleep",
...snipped...
"home",
"sleep"
]
],
"climates": [
{
"name": "Away",
"climateRef": "away",
...snipped...
"coolTemp": 788,
"heatTemp": 608
},
{
"name": "Home",
"climateRef": "home",
...snipped...
"coolTemp": 734,
"heatTemp": 707
},
{
"name": "Sleep",
"climateRef": "sleep",
...snipped...
"coolTemp": 752,
"heatTemp": 662
},
{
"name": "Warm",
"isOccupied": true,
"isOptimized": false,
"coolFan": "auto",
"heatFan": "auto",
"vent": "off",
"ventilatorMinOnTime": 20,
"owner": "system",
"type": "program",
"coolTemp": 752,
"heatTemp": 740
}
]
}
}
}
The new program changes Monday from 04:00 (starting on the 9th element) to 05:30 to use the "home" climate instead of the previous "sleep" climate. We also created a new Warm climate with a heat temperature of 740, which is 74.0℉. Execute the following cURL command to perform the POST request.
curl -s --request POST --data-urlencode @new_pgm.txt -H "Content-Type: application/json;charset=UTF-8" -H "Expect:" -H "Authorization: Bearer ACCESS_TOKEN" "https://api.ecobee.com/1/thermostat?format=json"
Upon a successful change, you should receive:
{
"status": {
"code": 0,
"message": ""
}
}
Program changes are made by replacing the entire program. Therefore, to delete a climate simply omit the climate from the list. Default climates cannot be deleted. The file orig_pgm.txt contains the default program with the new Warm climate missing. Ensure to download the orig_pgm.txt file before executing the cURL command below.
curl -s --request POST --data-urlencode @orig_pgm.txt -H "Content-Type: application/json;charset=UTF-8" -H "Expect:" -H "Authorization: Bearer ACCESS_TOKEN" "https://api.ecobee.com/1/thermostat?format=json"
Now that we know about climates and comfort settings, let us create a hold using an existing climate settings in our next example.