The Tado API v2

Posted in Posted on 2017-01-07 15:00

I’ve been poking around in the Tado smart thermostat API again as the web application now uses v2. Here are the API calls I have found. Tado haven’t published their API so this could change and break at any time.

In the descriptions below I list the API call then an example curl command to make the call, followed by an example response. I have replaced some parts of the response with “xxx” (for strings) or “123” (for numbers) so as not to reveal my personal data.

To make any of the calls work, you first have to authenticate yourself (log in). For earlier versions of the API you could just log in and store a cookie but for v2 you need to authenticate using OAuth. To use OAuth you have to send over your username and password and you get a token back plus an expiry time (currently 10 minutes) and a special token you could use to refresh the first one without sending the password again. To get all this you use the following call:

$ curl -s "https://my.tado.com/oauth/token" -d client_id=tado-webapp -d grant_type=password -d password=yourPasssword -d scope=home.user -d username=you@yourEmail.whatever

That returns some JSON data:

{
  "access_token": "eyJraW...somethingReallyQuiteLong...0UQ",
  "token_type": "bearer",
  "refresh_token": "xxx",
  "expires_in": 599,
  "scope": "home.user"
}

If you don’t have curl installed then just do sudo apt-get install curl first (similarly for perl below). Obviously, you need to replace yourPassword with your password and you@yourEmail.whatever with your email address that you use to log in to your Tado account. The information is sent over HTTPS so it is encrypted and no-one can see the password.

To execute any other commands we need to get hold of just the access_token and save it. The following command does just that by running the output through a Perl regular expression and then saving it in /tmp/tadotoken:

$ curl -s "https://my.tado.com/oauth/token" -d client_id=tado-webapp -d grant_type=password -d password=yourPasssword -d scope=home.user -d username=you@yourEmail.whatever | perl -pe 's/^.*"access_token"\s*:\s*"([^"]*).*/$1/' > /tmp/tadotoken

To use some of the API you need to know your home’s ID number. You can get this using the /api/v2/me call. I have replaced my home ID with “99999” in the following documentation: you should insert yours instead.

Tado home API v2

/api/v2/me

$ curl "https://my.tado.com/api/v2/me" -H "Authorization: Bearer `cat /tmp/tadotoken`"
{
  "name": "xxx",
  "email": "xxx",
  "username": "xxx",
  "homes": [
    {
      "id": 99999,
      "name": "xxx"
    }
  ],
  "locale": "en_GB",
  "mobileDevices": [
    {
      "name": "xxx",
      "id": 12345,
      "settings": {
        "geoTrackingEnabled": true
      },
      "location": {
        "stale": true,
        "atHome": true,
        "bearingFromHome": {
          "degrees": 152.29927711986,
          "radians": 2.6581238341488
        },
        "relativeDistanceFromHomeFence": 0
      },
      "deviceMetadata": {
        "platform": "Android",
        "osVersion": "1.2.3",
        "model": "xxx",
        "locale": "en"
      }
    },
    etc
  ]
}

/api/v2/homes/99999

$ curl "https://my.tado.com/api/v2/homes/99999" -H "Authorization: Bearer `cat /tmp/tadotoken`"
{
  "id": 99999,
  "name": "Phillips",
  "dateTimeZone": "Europe\/London",
  "temperatureUnit": "CELSIUS",
  "installationCompleted": true,
  "partner": null,
  "simpleSmartScheduleEnabled": true,
  "contactDetails": {
    "name": "Stephen C Phillips",
    "email": "xxx",
    "phone": "+4412345678901"
  },
  "address": {
    "addressLine1": "xxx",
    "addressLine2": null,
    "zipCode": "xxx",
    "city": "Southampton",
    "state": null,
    "country": "GBR"
  },
  "geolocation": {
    "latitude": 50.1234567,
    "longitude": -1.1234567
  }
}

/api/v2/homes/99999/weather

$ curl "https://my.tado.com/api/v2/homes/99999/weather" -H "Authorization: Bearer `cat /tmp/tadotoken`"
{
  "solarIntensity": {
    "type": "PERCENTAGE",
    "percentage": 15.06,
    "timestamp": "2017-01-07T14:36:43.507Z"
  },
  "outsideTemperature": {
    "celsius": 10.25,
    "fahrenheit": 50.45,
    "timestamp": "2017-01-07T14:36:43.507Z",
    "type": "TEMPERATURE",
    "precision": {
      "celsius": 0.01,
      "fahrenheit": 0.01
    }
  },
  "weatherState": {
    "type": "WEATHER_STATE",
    "value": "SCATTERED_RAIN",
    "timestamp": "2017-01-07T14:36:43.507Z"
  }
}

/api/v2/homes/99999/devices

$ curl "https://my.tado.com/api/v2/homes/99999/devices" -H "Authorization: Bearer `cat /tmp/tadotoken`"
[
  {
    "deviceType": "BU01",
    "serialNo": "BUxxx",
    "shortSerialNo": "BUx",
    "currentFwVersion": "12.34",
    "connectionState": {
      "value": true,
      "timestamp": "2017-01-07T14:28:41.122Z"
    },
    "characteristics": {
      "capabilities": [
        "IDENTIFY"
      ]
    }
  },
  {
    "deviceType": "GW02",
    "serialNo": "GWxxx",
    "shortSerialNo": "GWx",
    "currentFwVersion": "12.3",
    "connectionState": {
      "value": true,
      "timestamp": "2017-01-07T14:41:07.547Z"
    },
    "characteristics": {
      "capabilities": [

      ]
    },
    "gatewayOperation": "NORMAL"
  },
  {
    "deviceType": "RU01",
    "serialNo": "RUxxx",
    "shortSerialNo": "RUx",
    "currentFwVersion": "12.34",
    "connectionState": {
      "value": true,
      "timestamp": "2017-01-07T14:25:04.634Z"
    },
    "characteristics": {
      "capabilities": [
        "INSIDE_TEMPERATURE_MEASUREMENT",
        "IDENTIFY"
      ]
    }
  }
]

/api/v2/homes/99999/installations

$ curl "https://my.tado.com/api/v2/homes/99999/installations" -H "Authorization: Bearer `cat /tmp/tadotoken`"
[
  {
    "id": 0,
    "type": "SALE_FITTING_ST_G1",
    "revision": 1,
    "state": "COMPLETED",
    "devices": [
      {
        "deviceType": "BU01",
        "serialNo": "BUxxx",
        "shortSerialNo": "BUx",
        "currentFwVersion": "12.34",
        "connectionState": {
          "value": true,
          "timestamp": "2017-01-07T14:28:41.122Z"
        },
        "characteristics": {
          "capabilities": [
            "IDENTIFY"
          ]
        }
      },
      {
        "deviceType": "RU01",
        "serialNo": "RUxxx",
        "shortSerialNo": "RUx",
        "currentFwVersion": "12.34",
        "connectionState": {
          "value": true,
          "timestamp": "2017-01-07T14:25:04.634Z"
        },
        "characteristics": {
          "capabilities": [
            "INSIDE_TEMPERATURE_MEASUREMENT",
            "IDENTIFY"
          ]
        }
      }
    ]
  }
]

/api/v2/homes/99999/mobileDevices

$ curl "https://my.tado.com/api/v2/homes/99999/mobileDevices" -H "Authorization: Bearer `cat /tmp/tadotoken`"
[
  {
    "name": "xxx",
    "id": 12345,
    "settings": {
      "geoTrackingEnabled": true
    },
    "location": {
      "stale": true,
      "atHome": true,
      "bearingFromHome": {
        "degrees": 152.29927711986,
        "radians": 2.6581238341488
      },
      "relativeDistanceFromHomeFence": 0
    },
    "deviceMetadata": {
      "platform": "Android",
      "osVersion": "1.2.3",
      "model": "xxx",
      "locale": "en"
    }
  },
  etc
]

/api/v2/homes/99999/zones

$ curl "https://my.tado.com/api/v2/homes/99999/zones" -H "Authorization: Bearer `cat /tmp/tadotoken`"
[
  {
    "id": 1,
    "name": "Heating",
    "type": "HEATING",
    "deviceTypes": [
      "BU01",
      "RU01"
    ],
    "devices": [
      {
        "deviceType": "BU01",
        "serialNo": "BUxxx",
        "shortSerialNo": "BUx",
        "currentFwVersion": "12.34",
        "connectionState": {
          "value": true,
          "timestamp": "2017-01-07T14:28:41.122Z"
        },
        "characteristics": {
          "capabilities": [
            "IDENTIFY"
          ]
        },
        "duties": [
          "CIRCUIT_DRIVER"
        ]
      },
      {
        "deviceType": "RU01",
        "serialNo": "RUxxx",
        "shortSerialNo": "RUx",
        "currentFwVersion": "12.34",
        "connectionState": {
          "value": true,
          "timestamp": "2017-01-07T14:25:04.634Z"
        },
        "characteristics": {
          "capabilities": [
            "INSIDE_TEMPERATURE_MEASUREMENT",
            "IDENTIFY"
          ]
        },
        "duties": [
          "ZONE_UI",
          "ZONE_LEADER"
        ]
      }
    ],
    "reportAvailable": true,
    "supportsDazzle": true,
    "dazzleEnabled": true
  },
  {
    "id": 0,
    "name": "Hot Water",
    "type": "HOT_WATER",
    "deviceTypes": [
      "BU01",
      "RU01"
    ],
    "devices": [
      {
        "deviceType": "BU01",
        "serialNo": "BUxxx",
        "shortSerialNo": "BUx",
        "currentFwVersion": "12.34",
        "connectionState": {
          "value": true,
          "timestamp": "2017-01-07T14:28:41.122Z"
        },
        "characteristics": {
          "capabilities": [
            "IDENTIFY"
          ]
        },
        "duties": [
          "ZONE_DRIVER"
        ]
      },
      {
        "deviceType": "RU01",
        "serialNo": "RUxxx",
        "shortSerialNo": "RUx",
        "currentFwVersion": "12.34",
        "connectionState": {
          "value": true,
          "timestamp": "2017-01-07T14:25:04.634Z"
        },
        "characteristics": {
          "capabilities": [
            "INSIDE_TEMPERATURE_MEASUREMENT",
            "IDENTIFY"
          ]
        },
        "duties": [
          "ZONE_UI",
          "ZONE_LEADER"
        ]
      }
    ],
    "reportAvailable": false,
    "supportsDazzle": false,
    "dazzleEnabled": true
  }
]

/api/v2/homes/99999/zones/0/state

$ curl "https://my.tado.com/api/v2/homes/99999/zones/0/state" -H "Authorization: Bearer `cat /tmp/tadotoken`"
{
  "tadoMode": "HOME",
  "geolocationOverride": true,
  "geolocationOverrideDisableTime": "2017-01-07T18:00:00Z",
  "preparation": null,
  "setting": {
    "type": "HOT_WATER",
    "power": "OFF",
    "temperature": null
  },
  "overlayType": null,
  "overlay": null,
  "link": {
    "state": "ONLINE"
  },
  "activityDataPoints": {

  },
  "sensorDataPoints": {

  }
}

/api/v2/homes/99999/zones/0/capabilities

$ curl "https://my.tado.com/api/v2/homes/99999/zones/0/capabilities" -H "Authorization: Bearer `cat /tmp/tadotoken`"
{
  "type": "HOT_WATER",
  "canSetTemperature": false
}

/api/v2/homes/99999/zones/1/state

$ curl "https://my.tado.com/api/v2/homes/99999/zones/1/state" -H "Authorization: Bearer `cat /tmp/tadotoken`"
{
  "tadoMode": "HOME",
  "geolocationOverride": false,
  "geolocationOverrideDisableTime": null,
  "preparation": null,
  "setting": {
    "type": "HEATING",
    "power": "ON",
    "temperature": {
      "celsius": 19.5,
      "fahrenheit": 67.1
    }
  },
  "overlayType": null,
  "overlay": null,
  "link": {
    "state": "ONLINE"
  },
  "activityDataPoints": {
    "heatingPower": {
      "type": "PERCENTAGE",
      "percentage": 20,
      "timestamp": "2017-01-07T14:30:59.439Z"
    }
  },
  "sensorDataPoints": {
    "insideTemperature": {
      "celsius": 19.37,
      "fahrenheit": 66.87,
      "timestamp": "2017-01-07T14:24:48.623Z",
      "type": "TEMPERATURE",
      "precision": {
        "celsius": 0.1,
        "fahrenheit": 0.1
      }
    },
    "humidity": {
      "type": "PERCENTAGE",
      "percentage": 58.7,
      "timestamp": "2017-01-07T14:24:48.623Z"
    }
  }
}

/api/v2/homes/99999/zones/1/capabilities

$ curl "https://my.tado.com/api/v2/homes/99999/zones/1/capabilities" -H "Authorization: Bearer `cat /tmp/tadotoken`"
{
  "type": "HEATING",
  "temperatures": {
    "celsius": {
      "min": 5,
      "max": 25,
      "step": 0.1
    },
    "fahrenheit": {
      "min": 41,
      "max": 77,
      "step": 0.1
    }
  }
}

/api/v2/homes/99999/zones/1/schedule/activeTimetable

$ curl "https://my.tado.com/api/v2/homes/99999/zones/1/schedule/activeTimetable" -H "Authorization: Bearer `cat /tmp/tadotoken`"
{
  "id": 1,
  "type": "THREE_DAY"
}

Comments

Comments powered by Disqus