The Tado API

Posted in Posted on 2016-01-16 16:16

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.

Attention!

Edit 2017-01-12: Please note that I have since documented v2 of the Tado API in another post.

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&j_username=you@yourEmail.whatever" --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 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. 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.

Tado home API v1

/api/v1/me

$ 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"
}

/api/v1/home/99999

$ 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"
}

/api/v1/home/99999/devices

$ 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"
        }
]

/api/v1/home/99999/hvacState

$ 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"
        }
}

/api/v1/home/99999/installationProcess

$ 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
}

/api/v1/home/99999/weather

$ 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"
        }
}

Tado mobile API v1.6

/mobile/1.6/getAppUsers

$ 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
}

/mobile/1.6/getAppUsersRelativePositions

$ 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
        }
}

/mobile/1.6/getCurrentState

$ 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
}

/mobile/1.6/getCurrentWeather

$ 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"
}

/mobile/1.6/getHomeInfo

$ 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
}

/mobile/1.6/getHotWaterScheduleContainer

$ 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...
                        }
                }
        }
}

/mobile/1.6/getLocale

$ curl "https://my.tado.com/mobile/1.6/getLocale" -H "Referer: https://my.tado.com/" --cookie /tmp/tadocookies
{
        "locale": "en_GB",
        "success": true
}

/mobile/1.6/getThermostatSettings

$ 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
        }
}

Comments

Comments powered by Disqus