Tado API Guide - updated for 2019
api hacking IoT Smart Home tado · 63 comments · 1,400 words · Viewed ~33,423 times.
Tado is a brilliant smart thermostat. But their API is very poorly documented. This is an updated guide for 2019. I am indebted to Stephen C Phillips' original documentation.
Getting started
You will need:
- A Tado (duh!)
- Your Username (usually your email address)
- Your Password
- A Client Secret
Getting the client secret
I'm using this client secret: wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc This secret may change in the future. In the examples, I'll shorten it to wZa to make it easier to read. You will need to use the full length secret when running this code.
To get the current secret, you can visit https://my.tado.com/webapp/env.js and get the secret from there.
JavaScript
var TD = {
config: {
version: 'v587',
tgaRestApiEndpoint: 'https://my.tado.com/api/v1',
tgaRestApiV2Endpoint: 'https://my.tado.com/api/v2',
susiApiEndpoint: 'https://susi.tado.com/api',
oauth: {
clientApiEndpoint: 'https://my.tado.com/oauth/clients',
apiEndpoint: 'https://auth.tado.com/oauth',
clientId: 'tado-web-app',
clientSecret: 'wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc'
}
}
};
If that ever changes, you will need to open your web browser's development tools, and then look in the network tab. Then, log in to https://my.tado.com/webapp/.
You should see the token: 
Get Bearer Token
These examples use the curl command on Linux.
Here's how to turn your username and password into a "Bearer Token" - this is needed for every subsequent API call:
curl -s "https://auth.tado.com/oauth/token" -d client_id=tado-web-app -d grant_type=password -d scope=home.user -d username="you@example.com" -d password="Password123" -d client_secret=wZaThe response will be:
JSON
{
"access_token": "abc",
"token_type": "bearer",
"refresh_token": "def",
"expires_in": 599,
"scope": "home.user",
"jti": "xyz-123"
}
The real access_token will be very long. I've shortened it to abc make things easier to read in these examples.
The access token expires after 600 seconds. You can either request a new one with the username and password, or use the provided refresh_token like so:
curl -s "https://auth.tado.com/oauth/token" -d grant_type=refresh_token -d refresh_token=def -d client_id=tado-web-app -d scope=home.user -d client_secret=wZaGet your details
The next step is to get your homeId - this will also be needed for subsequent API calls:
curl -s "https://my.tado.com/api/v1/me" -H "Authorization: Bearer abc"You'll get back your data, like this:
{
"name": "Terence Eden",
"email": "you@example.com",
"username": "your_user_name",
"enabled": true,
"id": "987654321",
"homeId": 123456,
"locale": "en_GB",
"type": "WEB_USER"
}
Your homeId is what's important here. I'm going to use the example 123456 - you should use your own.
Check it all works
This request will check that you've got the right details.
curl -s "https://my.tado.com/api/v2/homes/123456" -H "Authorization: Bearer abc"You'll get back information about your installation. I've redacted mine for privacy.
{
"id": 123456,
"name": " ",
"dateTimeZone": "Europe/London",
"dateCreated": "2015-12-18T19:21:59.315Z",
"temperatureUnit": "CELSIUS",
"installationCompleted": true,
"partner": " ",
"simpleSmartScheduleEnabled": true,
"awayRadiusInMeters": 123.45,
"usePreSkillsApps": true,
"skills": [],
"christmasModeEnabled": true,
"contactDetails": {
"name": "Terence Eden",
"email": " ",
"phone": " "
},
"address": {
"addressLine1": " ",
"addressLine2": null,
"zipCode": " ",
"city": " ",
"state": null,
"country": "GBR"
},
"geolocation": {
"latitude": 12.3456789,
"longitude": -1.23456
},
"consentGrantSkippable": true
}
Get your data
OK, here's where the fun begins. This gets the data about your installation - including firmware details, device names, etc.
curl -s "https://my.tado.com/api/v2/homes/123456/zones" -H "Authorization: Bearer abc"Here's what you get back - I've redacted some of my details.
[{
"id": 1,
"name": "Heating",
"type": "HEATING",
"dateCreated": "2015-12-21T15:46:45.000Z",
"deviceTypes": ["RU01"],
"devices": [{
"deviceType": "RU01",
"serialNo": " ",
"shortSerialNo": " ",
"currentFwVersion": "54.8",
"connectionState": {
"value": true,
"timestamp": "2019-02-13T19:30:52.733Z"
},
"characteristics": {
"capabilities": ["INSIDE_TEMPERATURE_MEASUREMENT", "IDENTIFY", "OPEN_WINDOW_DETECTION"]
},
"batteryState": "NORMAL",
"duties": ["ZONE_UI", "ZONE_LEADER"]
}],
"reportAvailable": false,
"supportsDazzle": true,
"dazzleEnabled": true,
"dazzleMode": {
"supported": true,
"enabled": true
},
"openWindowDetection": {
"supported": true,
"enabled": true,
"timeoutInSeconds": 1800
}
}, {
"id": 0,
"name": "Hot Water",
"type": "HOT_WATER",
"dateCreated": "2016-10-03T11:31:42.272Z",
"deviceTypes": ["BU01", "RU01"],
"devices": [{
"deviceType": "BU01",
"serialNo": " ",
"shortSerialNo": " ",
"currentFwVersion": "49.4",
"connectionState": {
"value": true,
"timestamp": "2019-02-13T19:36:17.361Z"
},
"characteristics": {
"capabilities": []
},
"isDriverConfigured": true,
"duties": ["ZONE_DRIVER"]
}, {
"deviceType": "RU01",
"serialNo": " ",
"shortSerialNo": " ",
"currentFwVersion": "54.8",
"connectionState": {
"value": true,
"timestamp": "2019-02-13T19:30:52.733Z"
},
"characteristics": {
"capabilities": ["INSIDE_TEMPERATURE_MEASUREMENT", "IDENTIFY", "OPEN_WINDOW_DETECTION"]
},
"batteryState": "NORMAL",
"duties": ["ZONE_UI", "ZONE_LEADER"]
}],
"reportAvailable": false,
"supportsDazzle": false,
"dazzleEnabled": false,
"dazzleMode": {
"supported": false
},
"openWindowDetection": {
"supported": false
}
}]
State
This command will tell you if you're home or not. Or, in other words, whether the Tado thinks you're nearby:
curl -s https://my.tado.com/api/v2/homes/123465/state -H "Authorization: Bearer abc"This is what you'll get back if you're at home
{"presence":"HOME"}Zones
My Tado has two "Zones". 0 is for Hot Water, 1 is for Heating. Yours may be different.
Hot Water Information
curl -s https://my.tado.com/api/v2/homes/123456/zones/0/state -H "Authorization: Bearer abc"Here's information about your hot water:
{
"tadoMode": "HOME",
"geolocationOverride": false,
"geolocationOverrideDisableTime": null,
"preparation": null,
"setting": {
"type": "HOT_WATER",
"power": "OFF",
"temperature": null
},
"overlayType": null,
"overlay": null,
"openWindow": null,
"nextScheduleChange": {
"start": "2019-02-13T19:00:00Z",
"setting": {
"type": "HOT_WATER",
"power": "ON",
"temperature": null
}
},
"link": {
"state": "ONLINE"
},
"activityDataPoints": {},
"sensorDataPoints": {}
}
Heating
It's much the same for Heating information:
curl -s https://my.tado.com/api/v2/homes/123456/zones/1/state -H "Authorization: Bearer abc"This also gets you humidity data etc:
{
"tadoMode": "HOME",
"geolocationOverride": false,
"geolocationOverrideDisableTime": null,
"preparation": null,
"setting": {
"type": "HEATING",
"power": "ON",
"temperature": {
"celsius": 15.00,
"fahrenheit": 59.00
}
},
"overlayType": null,
"overlay": null,
"openWindow": null,
"nextScheduleChange": {
"start": "2019-02-13T17:30:00Z",
"setting": {
"type": "HEATING",
"power": "ON",
"temperature": {
"celsius": 18.00,
"fahrenheit": 64.40
}
}
},
"link": {
"state": "ONLINE"
},
"activityDataPoints": {
"heatingPower": {
"type": "PERCENTAGE",
"percentage": 0.00,
"timestamp": "2019-02-13T10:19:37.135Z"
}
},
"sensorDataPoints": {
"insideTemperature": {
"celsius": 16.59,
"fahrenheit": 61.86,
"timestamp": "2019-02-13T10:30:52.733Z",
"type": "TEMPERATURE",
"precision": {
"celsius": 0.1,
"fahrenheit": 0.1
}
},
"humidity": {
"type": "PERCENTAGE",
"percentage": 57.20,
"timestamp": "2019-02-13T10:30:52.733Z"
}
}
}
Weather
Tado also provides you with data about the external weather:
curl -s https://my.tado.com/api/v2/homes/123456/weather -H 'Authorization: Bearer abc'You get back a basic weather report for your location:
{
"solarIntensity": {
"type": "PERCENTAGE",
"percentage": 68.10,
"timestamp": "2019-02-10T10:35:00.989Z"
},
"outsideTemperature": {
"celsius": 8.00,
"fahrenheit": 46.40,
"timestamp": "2019-02-10T10:35:00.989Z",
"type": "TEMPERATURE",
"precision": {
"celsius": 0.01,
"fahrenheit": 0.01
}
},
"weatherState": {
"type": "WEATHER_STATE",
"value": "CLOUDY_PARTLY",
"timestamp": "2019-02-10T10:35:00.989Z"
}
}
Controlling your home
It's possible to turn the heating and hot water on / off.
Turn Heating On
This is a PUT request
curl -s 'https://my.tado.com/api/v2/homes/123456/zones/1/overlay' -X PUT -H 'Authorization: Bearer abc' -H 'Content-Type: application/json;charset=utf-8' --data '{"setting":{"type":"HEATING","power":"ON","temperature":{"celsius":21,"fahrenheit":69.8}},"termination":{"type":"MANUAL"}}'Just to make it easier to read, this is the JSON data that you have to PUT:
{
"setting": {
"type": "HEATING",
"power": "ON",
"temperature": {
"celsius": 21,
"fahrenheit": 69.8
}
},
"termination": {
"type": "MANUAL"
}
}
If it has worked, you'll get back this response:
{
"type": "MANUAL",
"setting": {
"type": "HEATING",
"power": "ON",
"temperature": {
"celsius": 21.00,
"fahrenheit": 69.80
}
},
"termination": {
"type": "MANUAL",
"projectedExpiry": null
}
}
End Manual Heading Mode
This is a simple DELETE command:
curl -s 'https://my.tado.com/api/v2/homes/123456/zones/1/overlay' -X DELETE -H 'Authorization: Bearer abc'Turn on Hot Water
Much the same as before
curl -s 'https://my.tado.com/api/v2/homes/123456/zones/0/overlay' -X PUT -H 'Content-Type: application/json;charset=utf-8' -H 'Authorization: Bearer abc'--data '{"setting":{"type":"HOT_WATER","power":"ON"},"termination":{"type":"MANUAL"}}'Turn off Hot Water
Again, a DELETE
curl -s 'https://my.tado.com/api/v2/homes/123456/zones/0/overlay' -X DELETE -H 'Authorization: Bearer abc'Historic Information
You can get a complete view of historic data with:
curl -s 'https://my.tado.com/api/v2/homes/123456/zones/1/dayReport?date=2018-02-14' -H 'Authorization: Bearer abc'The date at the end is in ISO8601 format. You'll receive info on internal and external temperature, humidity levels, whether the heating and hot water were on, and a few other bits and bobs.
What's Next?
There are a bunch of other things you can do with the API, like setting a schedule etc. Sadly, I don't have time to document them all. But this should be enough to get you detailed information, and basic control.
I'd love it if someone could make OpenAPI documentation for this.
Two years of home heating data
How many connected devices do you have at home?
Elliot West says:
Volker says:
Volker says:
Richard Swain says:
Martijn van der Woud says:
Richard says:
Omar says:
Victor says:
W says:
AndrewFG says:
AndrewFG says:
Andrew Fiddian-Green says:
Tim says:
Tim D says:
Michael Senger says:
Michael Senger says:
Joris says:
Georgi P says:
Jacopo Scarpellini says:
Mohit Mhatre says:
Jacopo Scarpellini says:
Jacopo Scarpellini says:
Jot Zet says:
jeroen says:
Christian says:
John says:
{ "homePresence": "AWAY" }Jadranko says:
Frédéric Mangeant says:
Stefano says:
Mathias Ditlevsen Bo says:
Stefano says:
Mathias Ditlevsen Bo says:
Stefano says:
Mathias Ditlevsen Bo says:
Vamp says:
Sütő Norbert says:
Norbert Suto says:
Sütő Norbert says:
Thor says:
@edent says:
Martin says:
@edent says:
Healy93 says:
Kevin says:
@edent says:
if( $battery_state != "NORMAL" )Ravus says:
David Hills says:
Matt says:
Matt says:
Matt says:
@edent says:
Dwane says:
Kristel says:
Henk-Jan says:
First of all, thanks for all the help. I got all api calls working that are read-only, but the put options don't work, they give the following error:
{"errors":[{"code":"accessDenied","title":"current user is not allowed to access this resource"}]}
Any idea what is wrong?
@edent says:
Hi Henk, This blog post is 5 years old - so may be outdated. Your best bet is to speak to Tado. But, from the error message, it looks like the user doesn't have the right permissions.