Tado API Guide - updated for 2019

by @edent | # # # # # | 22 comments | Read ~5,122 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.

22 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”}

  5. W says:

    Can anyone tell me if the ambient light sensor in the radiator valve is exposed in any of Tado's endpoints?

  6. AndrewFG says:

    Dear Terence,

    Many thanks for sharing this information. You asked if anyone has an OpenAPI specification for Tado, and I think that there is indeed one written by Dennis Frommknecht on the OpenHAB github on the link below.

    https://github.com/openhab/openhab2-addons/blob/master/bundles/org.openhab.binding.tado/src/main/api/tado-api.yaml

    I think his specification is not fully complete, and would benefit from being completed with your own knowledge added. For example, I want to add “device:batteryState” to this specification. Any thoughts?

    1. @edent says:

      I think you should add it - sounds like a great idea.

      1. AndrewFG says:

        😉

        I guess I was hoping that you might add some of your own knowledge too 🙂

        1. Andrew Fiddian-Green says:

          The YAML file for modified version of the OpenAPI specification for Tado devices is on the link below.

          https://github.com/openhab/openhab2-addons/blob/84e5c9be8f54bf9696828bacf0520b7ae77dc94e/bundles/org.openhab.binding.tado/src/main/api/tado-api.yaml

          Note: it is subject to a Pull Request to integrate modifications into the openHAB v2 Tado binding, so the link might change after the merge..

  7. Tim says:

    I guess they changed it again?! 😦

    It looks like hotwater zones don’t have an overlay and the DELETE command no longer works to turn hot water off.

    1. Tim D says:

      Looks like to turn things off is much the same as the turn on (PUT request) except with power set to OFF etc.

      Cheers.

  8. Michael Senger says:

    Hello,
    can someone tell me, what “usePreSkillsApps” is and what kind of data it will be show?

    1. @edent says:

      It's a boolean field. So it will only show true or false. But I don't know what it represents. I suggest asking Tado directly.

      1. Michael Senger says:

        Thanks
        I will contact tado

    2. Joris says:

      Tado changed their system to a subscription service that offers extra features. They are called “skills”.
      For instance in the old version (the one I have) having your heating turned on/off based on whether you are home is a free feature. In the current/new version if you buy a Tado system you have to pay a subscription to use this service.

      https://support.tado.com/hc/en-gb/articles/360015213512-What-is-Auto-Assist-

      I presume that that flag is used to determine if you are on the old or the new system.

  9. Georgi P says:

    If someone is interested here are the APIs to witch Home/Away mode and Open Window.
    It will work if you are not using the “auto-assist” (subscription) from Tado. In order to activate away mode you need to have geofencing active and away from home. For open window to work first an open window must be detected by Tado.

    Home/Away:
    PUT – https://my.tado.com/api/v2/homes//presence
    {
    “homePresence”: “AWAY”
    }

    Open Window:
    POST – https://my.tado.com/api/v2/homes//zones//state/openWindow/activate

  10. Is there a way to change the temperature offset using the API?
    This could be useful to solve the problems with the Smart TRV (the offset required depend on various factors and could be measured by an external sensors)

  11. Jacopo Scarpellini says:

    when I type the following in Putty connected to my hassio

    core-ssh:~# curl -s "https://auth.tado.com/o scope=home.user -d username="myname@gmail.com" -d password="12345" -d client_secret=wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc

    I get:

    {"error":"invalid_grant","error_description":"Bad credentials"}core-ssh:~#

    I've tried with and without " around username and password, no sure if they are needed; it doesn't work anyway

    Any idea?

    1. @edent says:

      I've just tried, and it appears to work for me. Do you have an special characters in your password?

      1. Jacopo Scarpellini says:

        No, although I have a + (plus) in the username

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.