Tado API Guide - updated for 2019

by @edent | # # # # # | 6 comments | Read ~2,124 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.

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:
Debug screen of a web browser.

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=wZa

The response will be:

{
    "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=wZa

Get 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.

6 thoughts on “Tado API Guide - updated for 2019

  1. Elliot West says:

    Thanks for your efforts on writing this up. I found it really useful for helping me get some Tado home metrics into AWS CloudWatch. If anyone is interested in doing similar, I have some Golang code here: https://github.com/teabot/tado-metrics

  2. great job! I’m developing a java library for interfacing with the tado API to make the work more convenient to all developers. if someone is interested can find the repository of the library here: https://github.com/GiorgioBertolotti/TadoJava
    Thanks!

  3. Volker says:

    Hi,

    Is there any way to control a Tado device only with a http/https request?
    I have a smarthome system, which can send http post, get and put commands.

    What I mean for Example is something like this:
    https://my.tado.com/api/v2/homes/123456/zones/1/overlay/&user=Name&pass=Word&heating=on&Temperature=20

    Is there any way to get this (or something like this) to work?

    Thank you!

    1. @edent says:

      No. Because every request needs to pass an Authorization header. You could build your own proxy service.

      1. Volker says:

        Hi,

        An Authorization in an URL is possible, I think.
        If I make a request like this:

        https://my.tado.com/api/v2/homes/MyHomeID/zones?username=MyUserName&password=MyPassWord

        ... I‘m receiving an answer, so the Authorization on this way works....!??

  4. Omar says:

    Hi, thanks for the info. What other termination types are supported? you listed the manual one but I’m looking for the dynamic one that terminates at the next scheduled time block
    “termination”:{“type”:”MANUAL”}

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.