Previous Example Next Example

Example 9: Creating a vacation

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:

To schedule a vacation with the thermostat, we have to use another function called CreateVacation .

If you want to learn more about how vacations are related to other events or objects of the thermostat, please refer to Example 5.

Create a json.txt file with the following JSON object. With this JSON, we will create a vacation starting from 8:00pm on March 15, 2016 to 8:00am on March 29, 2016 with both heat and cool temperature set to 66.0℉ and 78.0℉ respectively. 

{
  "selection": {
    "selectionType":"registered",
    "selectionMatch":""
  },
  "functions": [
    {
      "type":"createVacation",
      "params":{
        "name": "Skiing",
        "coolHoldTemp": 780,
        "heatHoldTemp": 660,
        "startDate": "2016-03-15",
        "startTime": "20:00:00",
        "endDate": "2016-03-29",
        "endTime": "08:00:00"
      }      
    }
  ]
}

Post our function using cURL. 

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 verify that the thermostat has our vacation. We use the GET Thermostat request and set the includeEvents property.

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\}\}'

There is now a new vacation event in our events list, with the appropriate hold temperatures that we specified earlier.

{
  "page": {
    "page": 1,
    "totalPages": 1,
    "pageSize": 1,
    "total": 1
  },
  "thermostatList": [
    {
      "identifier": "318324666667",
      "name": "Main Floor",
      "thermostatRev": "150213185952",
      "isRegistered": true,
      "modelNumber": "athenaSmart",
      "lastModified": "2015-02-13 18:59:52",
      "thermostatTime": "2015-02-13 14:00:41",
      "utcTime": "2015-02-13 19:00:41",
      "events": [
        {
          "type": "vacation",
          "name": "Skiing",
          "running": false,
          "startDate": "2016-03-15",
          "startTime": "20:00:00",
          "endDate": "2016-03-29",
          "endTime": "08:00:00",
          "isOccupied": false,
          "isCoolOff": false,
          "isHeatOff": false,
          "coolHoldTemp": 780,
          "heatHoldTemp": 660,
          "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": ""
        },
        {
          "type": "template",
          "name": "_Default_",
          "running": false,
          "startDate": "2035-01-01",
          "startTime": "00:00:00",
          "endDate": "2035-01-01",
          "endTime": "23:59:59",
          "isOccupied": false,
          "isCoolOff": false,
          "isHeatOff": false,
          "coolHoldTemp": 780,
          "heatHoldTemp": 660,
          "fan": "auto",
          "vent": "off",
          "ventilatorMinOnTime": 5,
          "isOptional": true,
          "isTemperatureRelative": false,
          "coolRelativeTemp": 40,
          "heatRelativeTemp": 40,
          "isTemperatureAbsolute": false,
          "dutyCyclePercentage": 255,
          "fanMinOnTime": 0,
          "occupiedSensorActive": false,
          "unoccupiedSensorActive": false,
          "drRampUpTemp": 0,
          "drRampUpTime": 3600,
          "linkRef": "",
          "holdClimateRef": ""
        }
      ]
    }
  ],
  "status": {
    "code": 0,
    "message": ""
  }
}

We mention about the _Default_ event in past. Notice that the coolHoldTemp and the heatHoldTemp of the default event inherited our vacation event's values. The default event will always hold the previous settings of the last vacation event created. To create a good user experience, it is a good practice that developers should use the values from the default event as the defaults for new vacation events. Users of your App can then override these defaults as they wish.

Note that vacation events cannot be removed with ResumeProgram .

In our next example, we will learn how to delete a vacation event.

Previous Example Next Example