The Tado API

I’ve been poking around in the Tado smart thermostat API to see what information there is available (for instance to send temperature data to Loggly). Here are the API calls I have found so far by looking at the web application only. 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” so as not to reveal my personal data. To make any of the calls work, you first have to log in using the following call:

$ curl "https://my.tado.com/j_spring_security_check?j_password=yourPassword&[email protected]" --data-binary "{}" --cookie-jar /tmp/tadocookies

If you don’t have “curl” installed then just do sudo apt-get install curl first. Obviously, you need to replace yourPassword with your password and [email protected] 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. The command does the login and saves the cookies that are sent back into the file /tmp/tadocookies.

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

$ curl "https://my.tado.com/api/v1/me" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "name": "Firstname Surname",
        "email": "xxx",
        "username": "xxx",
        "enabled": true,
        "homeId": 99999,
        "locale": "en_GB",
        "type": "WEB_USER"
}

$ curl "https://my.tado.com/api/v1/home/99999" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "id": 99999,
        "name": "YourName",
        "address": {
                "name": "Firstname Surname",
                "addressLine1": "xxx",
                "addressLine2": null,
                "zipCode": "xxx",
                "city": "xxx",
                "state": null,
                "country": "GBR",
                "email": "xxx",
                "phone": "+44xxx",
                "phone2": null
        },
        "dateTimeZone": "Europe/London",
        "installationCompleted": true,
        "tadoSystemType": "HEATING"
}

$ curl "https://my.tado.com/api/v1/home/99999/devices" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

[
        {
                "deviceType": "RU01",
                "serialNo": "xxx",
                "shortSerialNo": "xxx",
                "isReadyToInstall": true,
                "connected": true,
                "connectionState": {
                        "value": true,
                        "timestamp": "2016-01-16T14:58:24.303Z"
                },
                "registeredToHome": true,
                "thermInterfaceType": "TEMP_SENSOR",
                "canBeHotWaterDriver": true,
                "hotWaterControl": false,
                "hotWaterTemperatureControl": false,
                "authKey": "xxx"
        },
        {
                "deviceType": "GW02",
                "serialNo": "xxx",
                "shortSerialNo": "xxx",
                "isReadyToInstall": true,
                "connected": true,
                "connectionState": {
                        "value": true,
                        "timestamp": "2016-01-16T14:57:33.709Z"
                },
                "registeredToHome": true,
                "authKey": "xxx"
        },
        {
                "deviceType": "BU01",
                "serialNo": "xxx",
                "shortSerialNo": "xxx",
                "isReadyToInstall": true,
                "connected": true,
                "connectionState": {
                        "value": true,
                        "timestamp": "2016-01-16T14:58:22.991Z"
                },
                "registeredToHome": true,
                "thermInterfaceType": "GENERIC_RELAY_NO",
                "canBeHotWaterDriver": true,
                "hotWaterControl": true,
                "hotWaterTemperatureControl": false,
                "authKey": "xxx"
        }
]

$ curl "https://my.tado.com/api/v1/home/99999/hvacState" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "tadoMode": "HOME",
        "geolocationOverride": false,
        "setting": {
                "type": "HEATING",
                "power": "ON",
                "temperature": {
                        "celsius": 20,
                        "fahrenheit": 68
                }
        },
        "overlay": null,
        "insideTemperature": {
                "celsius": 20.1,
                "fahrenheit": 68.18,
                "timestamp": "2016-01-16T14:58:24.241Z",
                "type": "TEMPERATURE"
        },
        "humidity": {
                "type": "PERCENTAGE",
                "percentage": 52,
                "timestamp": "2016-01-16T14:58:24.241Z"
        }
}

$ curl "https://my.tado.com/api/v1/home/99999/installationProcess" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "id": xxx,
        "type": "SALE_FITTING_ST_G1",
        "installationType": "SALE_FITTING",
        "targetProductSetType": "ST_G1",
        "revision": 1,
        "state": "COMPLETED",
        "recordingId": null
}

$ curl "https://my.tado.com/api/v1/home/99999/weather" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "solarIntensity": {
                "type": "PERCENTAGE",
                "percentage": 48,
                "timestamp": "2016-01-16T14:58:24.241Z"
        },
        "outsideTemperature": {
                "celsius": 2,
                "fahrenheit": 35.6,
                "timestamp": "2016-01-16T14:58:24.241Z",
                "type": "TEMPERATURE"
        },
        "weatherState": {
                "value": "SUN",
                "timestamp": "2016-01-16T13:07:14.516Z"
        }
}

$ curl "https://my.tado.com/mobile/1.6/getAppUsers" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "success": true,
        "appUsers": [
                {
                        "id": zzzzzz,
                        "nickname": "Your phone",
                        "username": "homeID_devicename",
                        "geoTrackingEnabled": true,
                        "privacyEnabled": false,
                        "geolocationIsStale": false
                },
                ...etc...
        ],
        "currentUserId": zzzzzz
}

$ curl "https://my.tado.com/mobile/1.6/getAppUsersRelativePositions" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "success": true,
        "appUsers": [
                {
                        "nickname": "xxx",
                        "username": "homeID_devicename",
                        "geoTrackingEnabled": true,
                        "privacyEnabled": false,
                        "geolocationIsStale": false,
                        "relativePosition": 0
                },
                ...etc...
        ],
        "geoMapScale": {
                "0": 20,
                "100": 8
        }
}

$ curl "https://my.tado.com/mobile/1.6/getCurrentState" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "success": true,
        "operation": "HOME",
        "preheating": false,
        "preheatingTargetOperation": null,
        "autoOperation": "HOME",
        "operationTrigger": "SYSTEM",
        "insideTemp": 20.1,
        "setPointTemp": 20,
        "controlPhase": "STEADY",
        "currentUserPrivacyEnabled": null,
        "currentUserGeoStale": null,
        "deviceUpdating": false,
        "homeId": 99999,
        "heatingOn": false,
        "internetGatewayType": "GW02",
        "internetGatewayConnected": true,
        "heatingMuscleType": "BU01",
        "heatingMuscleConnected": true,
        "insideTemperatureSensorType": "RU01",
        "insideTemperatureSensorConnected": true,
        "settingsEnabled": true,
        "fallbackOperation": false,
        "helpUrl": "https://support.tado.com/hc/",
        "pendingDeviceInstallation": false
}

$ curl "https://my.tado.com/mobile/1.6/getCurrentWeather" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "success": true,
        "temperature": 2,
        "conditionCode": 34,
        "dayPhase": "DAY",
        "location": "xxx"
}

$ curl "https://my.tado.com/mobile/1.6/getHomeInfo" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "success": true,
        "address": {
                "name": "xxx",
                "addressLine1": "xxx",
                "addressLine2": null,
                "zipCode": "xxx",
                "city": "xxx",
                "state": null,
                "countryCode": "xxx",
                "country": "xxx"
        },
        "email": "xxx",
        "name": "xxx",
        "phone": "+44xxx",
        "dateTimeZone": "Europe/London",
        "partner": null,
        "username": "xxx",
        "latitude": xxx,
        "longitude": xxx
}

$ curl "https://my.tado.com/mobile/1.6/getHotWaterScheduleContainer" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "success": true,
        "scheduleContainer": {
                "currentScheduleType": "THREEDAY",
                "schedules": {
                        "ONEDAY": {
                                "MONDAY_TO_SUNDAY": [
                                        {
                                                "time": "00:00",
                                                "eventType": "OFF"
                                        },
                                        {
                                                "time": "07:00",
                                                "eventType": "ON"
                                        },
                                        {
                                                "time": "22:00",
                                                "eventType": "OFF"
                                        }
                                ]
                        },
                        "THREEDAY": {
                                ...etc...
                        },
                        "SEVENDAY": {
                                ...etc...
                        }
                }
        }
}

$ curl "https://my.tado.com/mobile/1.6/getLocale" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "locale": "en_GB",
        "success": true
}

$ curl "https://my.tado.com/mobile/1.6/getThermostatSettings" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies

{
        "success": true,
        "setMode": "AUTO",
        "manualTemp": 21,
        "homeTemp": 19.4,
        "sleepTemp": 10,
        "comfortLevel": 50,
        "minAwayTemp": 8,
        "hotWaterControl": true,
        "hotWaterTempControl": false,
        "hotWaterMode": "SCHEDULE",
        "hotWaterTemp": 0,
        "hasExternalTempSensor": false,
        "useExternalTempSensor": false,
        "useBlockSchedule": true,
        "temperatures": {
                "box": 29.33,
                "externalTempSensor": null
        }
}