Previous Example Next Example

Example 12: Telling your thermostat you are away

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.

Access Token:

In a previous example, we learned how to create a temperature hold. There is another way to create a hold and that is to reference a climate. In this example, we will instruct the thermostat to hold on the away climate.

We begin by creating the following json.txt file with the following contents. The holdClimateRef parameter of the SetHold function should refer to the climateRef of the desirable Climate object. 

{
  "selection": {
    "selectionType":"registered",
    "selectionMatch":""
  },
  "functions": [
    {
      "type":"setHold",
      "params":{
        "holdType":"nextTransition",
        "holdClimateRef":"away"
      }
    }
  ]
}

Send the request with the following cURL command: 

curl -s --request POST --data-urlencode @json.txt -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer ACCESS_TOKEN" "https://api.ecobee.com/1/thermostat?format=json"

If the post is successful, you should see this.

{
  "status": {
    "code": 0,
    "message": ""
  }
}

Let us validate whether the hold is in effect, by querying the events of the thermostat.

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":"","includeEvents":true\}\}'

You should see an event with a holdClimateRef property as the first element in the events list returned. 

{
  "page": {
    "page": 1,
    "totalPages": 1,
    "pageSize": 1,
    "total": 1
  },
  "thermostatList": [
    {
      "identifier": "318324666667",
      "name": "Main Floor",
      "thermostatRev": "150217154621",
      "isRegistered": true,
      "modelNumber": "athenaSmart",
      "lastModified": "2015-02-17 15:46:21",
      "thermostatTime": "2015-02-17 10:46:45",
      "utcTime": "2015-02-17 15:46:45",
      "runtime": {
        "runtimeRev": "150217154126",
        "connected": true,
        "firstConnected": "2014-12-21 21:53:31",
        "connectDateTime": "2015-02-17 15:32:10",
        "disconnectDateTime": "2015-02-11",
        "lastModified": "2015-02-17 15:46:21",
        "lastStatusModified": "2015-02-17 15:41:26",
        "runtimeDate": "2015-02-17",
        "runtimeInterval": 185,
        "actualTemperature": 715,
        "actualHumidity": 35,
        "desiredHeat": 608,
        "desiredCool": 788,
        "desiredHumidity": 36,
        "desiredDehumidity": 60,
        "desiredFanMode": "auto"
      },
      "events": [
        {
          "type": "hold",
          "name": "auto",
          "running": true,
          "startDate": "2015-02-17",
          "startTime": "10:46:21",
          "endDate": "2015-02-17",
          "endTime": "23:30:00",
          "isOccupied": true,
          "isCoolOff": false,
          "isHeatOff": false,
          "coolHoldTemp": 788,
          "heatHoldTemp": 608,
          "fan": "auto",
          "vent": "off",
          "ventilatorMinOnTime": 5,
          "isOptional": true,
          "isTemperatureRelative": false,
          "coolRelativeTemp": 0,
          "heatRelativeTemp": 0,
          "isTemperatureAbsolute": true,
          "dutyCyclePercentage": 255,
          "fanMinOnTime": 0,
          "occupiedSensorActive": false,
          "unoccupiedSensorActive": false,
          "drRampUpTemp": 0,
          "drRampUpTime": 3600,
          "linkRef": "",
          "holdClimateRef": "away"
        }
        ...snipped...

You can use the same technique to tell the thermostat that you are home. Simply use the default home climate instead of away.

If you want to learn more about climates (or comfort settings), visit this example.

To cancel the away climate hold, simply call the ResumeProgram in this example.

We've been able to read the thermostat settings, program its behaviour, and override its program with by requesting a hold. In our final example, will request a historical runtime report of the thermostat.

Previous Example Next Example