Previous Example Next Example

Example 2: Obtaining your current actual temperature

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.

Once you've attained a valid access token, you can now use the access token along with your API Key to perform a request.

From this point on, all examples will show snippets of cURL. Any snippet text shown as red and underlined represents an access token that you can override with your own value by using the input field at the top of each example.

Below is a sample request to obtain our list of registered thermostats along with its runtime information.

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

You should now see a JSON output which includes the current thermostat runtimes.

								
{
  "page": {
    "page": 1,
    "totalPages": 1,
    "pageSize": 1,
    "total": 1
  },
  "thermostatList": [
    {
      "identifier": "318324702718",
      "name": "Main Floor",
      "thermostatRev": "150211193847",
      "isRegistered": true,
      "modelNumber": "athenaSmart",
      "lastModified": "2015-02-11 19:38:47",
      "thermostatTime": "2015-02-11 15:58:03",
      "utcTime": "2015-02-11 20:58:03",
      "runtime": {
        "runtimeRev": "150211205524",
        "connected": true,
        "firstConnected": "2014-12-21 21:53:31",
        "connectDateTime": "2015-02-11 20:48:08",
        "disconnectDateTime": "2015-02-11",
        "lastModified": "2015-02-11 20:55:24",
        "lastStatusModified": "2015-02-11 20:55:24",
        "runtimeDate": "2015-02-11",
        "runtimeInterval": 248,
        "actualTemperature": 711,
        "actualHumidity": 42,
        "desiredHeat": 707,
        "desiredCool": 734,
        "desiredHumidity": 36,
        "desiredDehumidity": 60,
        "desiredFanMode": "auto"
      }
    }
  ],
  "status": {
    "code": 0,
    "message": ""
  }
}						

From the above response, you will find the actual temperature and humidity. Below is the same structure highlighted.

"runtime": {
     ...snipped...
   "actualTemperature": 711,
   "actualHumidity": 42,
   "desiredHeat": 707,
   "desiredCool": 734,
     ...snipped...
   "desiredFanMode": "auto"
}

The temperature values are all provided in units of 0.1 of a Fahrenheit (℉). For example, our actualTemperature of 711 is actually 71.1℉. It is up to the caller of the API to convert to Celsius (℃). You can use the following formula:

(711 - 320) * 5 / 90 = 21.7℃  							
							

A thermostat has many properties. A complete list can be found in the Thermostat object reference. Certain properties are complex enough that they require their own object structures. The runtime property points to data defined by the Runtime object. Another example is the settings property, which points to an instance of Settings object. By default these object properties of the Thermostat are excluded. The selection JSON object within the body parameter of our request is used to determine which object properties will be returned. For more information reference the Selection object.

Let us take a closer look at the selection property that we passed in earlier with cURL.

{
  "selection":{
    "selectionType":"registered",
    "selectionMatch":"",
    "includeRuntime":true
  }
}							
							

Note that the backslashes were removed, because they were only needed with cURL on the command line.

For each object properties in the Thermostat object, you will find a corresponding include... property in the Selection object. For example, if we want to retrieve the Thermostat settings instead of its runtime, we can send 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":"","includeSettings":true\}\}'
                			

You can also combine multiple object properties in a single request. For example, let us retrieve the runtime and alerts at the same time.

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

Experiment by setting more include... properties of the Selection object in the request.

Now let us see how we can determine the thermostat mode with our next example.

Previous Example Next Example