API Class Methods¶
Most of the functions receive JSON from the API and translate it to a Python dictionary or a list of Python dictionaries. So the return value will depend on the behaviour of the API.
Getter¶
Air comfort¶
-
class
libtado.api.Tado.get_air_comfort¶ Get all zones of your home.
Returns: A list of dictionaries with all your zones. Return type: list Example
{ "freshness":{ "value":"FAIR", "lastOpenWindow":"2020-09-04T10:38:57Z" }, "comfort":[ { "roomId":1, "temperatureLevel":"COMFY", "humidityLevel":"COMFY", "coordinate":{ "radial":0.36, "angular":323 } }, { "roomId":4, "temperatureLevel":"COMFY", "humidityLevel":"COMFY", "coordinate":{ "radial":0.43, "angular":324 } } ] }
Air comfort geoloc¶
-
class
libtado.api.Tado.get_air_comfort_geoloc¶ Get all zones of your home.
Parameters: - latitude (float) – The latitude of the home.
- longitude (float) – The longitude of the home.
Returns: A dict of lists of dictionaries with all your rooms.
Return type: list
Example
{ "roomMessages":[ { "roomId":4, "message":"Bravo ! L’air de cette pièce est proche de la perfection.", "visual":"success", "link":null }, { "roomId":1, "message":"Continuez à faire ce que vous faites ! L'air de cette pièce est parfait.", "visual":"success", "link":null } ], "outdoorQuality":{ "aqi":{ "value":81, "level":"EXCELLENT" }, "pollens":{ "dominant":{ "level":"LOW" }, "types":[ { "localizedName":"Graminées", "type":"GRASS", "localizedDescription":"Poaceae", "forecast":[ { "localizedDay":"Auj.", "date":"2020-09-06", "level":"NONE" }, { "localizedDay":"Lun", "date":"2020-09-07", "level":"NONE" }, { "localizedDay":"Mar", "date":"2020-09-08", "level":"NONE" } ] }, { "localizedName":"Herbacées", "type":"WEED", "localizedDescription":"Armoise, Ambroisie, Pariétaire", "forecast":[ { "localizedDay":"Auj.", "date":"2020-09-06", "level":"NONE" }, { "localizedDay":"Lun", "date":"2020-09-07", "level":"NONE" }, { "localizedDay":"Mar", "date":"2020-09-08", "level":"NONE" } ] }, { "localizedName":"Arbres", "type":"TREE", "localizedDescription":"Aulne, Frêne, Bouleau, Noisetier, Cyprès, Olivier", "forecast":[ { "localizedDay":"Auj.", "date":"2020-09-06", "level":"NONE" }, { "localizedDay":"Lun", "date":"2020-09-07", "level":"NONE" }, { "localizedDay":"Mar", "date":"2020-09-08", "level":"NONE" } ] } ] }, "pollutants":[ { "localizedName":"Matière particulaire", "scientificName":"PM<sub>10</sub>", "level":"EXCELLENT", "concentration":{ "value":8.75, "units":"μg/m<sup>3</sup>" } }, { "localizedName":"Matière particulaire", "scientificName":"PM<sub>2.5</sub>", "level":"EXCELLENT", "concentration":{ "value":5.04, "units":"μg/m<sup>3</sup>" } }, { "localizedName":"Ozone", "scientificName":"O<sub>3</sub>", "level":"EXCELLENT", "concentration":{ "value":23.86, "units":"ppb" } }, { "localizedName":"Dioxyde de soufre", "scientificName":"SO<sub>2</sub>", "level":"EXCELLENT", "concentration":{ "value":1.19, "units":"ppb" } }, { "localizedName":"Monoxyde de carbone", "scientificName":"CO", "level":"EXCELLENT", "concentration":{ "value":266.8, "units":"ppb" } }, { "localizedName":"Dioxyde d'azote", "scientificName":"NO<sub>2</sub>", "level":"EXCELLENT", "concentration":{ "value":5.76, "units":"ppb" } } ] } }
Away configuration¶
-
class
libtado.api.Tado.get_away_configuration¶ Get the away configuration for a zone
Parameters: zone (int) – The zone ID. Returns: dict
Capabilities¶
-
class
libtado.api.Tado.get_capabilities¶ Parameters: zone (int) – The zone ID. Returns: The capabilities of a tado zone as dictionary. Return type: dict Example
{ 'temperatures': { 'celsius': {'max': 25, 'min': 5, 'step': 1.0}, 'fahrenheit': {'max': 77, 'min': 41, 'step': 1.0} }, 'type': 'HEATING' }
Default overlay¶
-
class
libtado.api.Tado.get_default_overlay¶ Get the default overlay settings of a zone
Parameters: zone (int) – The zone ID. Returns: dict Example
{ "terminationCondition": { "type": "TADO_MODE" } }
Device usage¶
-
class
libtado.api.Tado.get_device_usage¶ Get all devices of your home with how they are used
Returns: All devices of home as list of dictionaries Return type: list
Devices¶
-
class
libtado.api.Tado.get_devices¶ Returns: All devices of the home as a list of dictionaries. Return type: list Example
[ { 'characteristics': { 'capabilities': [] }, 'connectionState': { 'timestamp': '2017-02-20T18:51:47.362Z', 'value': True }, 'currentFwVersion': '25.15', 'deviceType': 'GW03', 'gatewayOperation': 'NORMAL', 'serialNo': 'SOME_SERIAL', 'shortSerialNo': 'SOME_SERIAL' }, { 'characteristics': { 'capabilities': [ 'INSIDE_TEMPERATURE_MEASUREMENT', 'IDENTIFY'] }, 'connectionState': { 'timestamp': '2017-01-22T16:03:00.773Z', 'value': False }, 'currentFwVersion': '36.15', 'deviceType': 'VA01', 'mountingState': { 'timestamp': '2017-01-22T15:12:45.360Z', 'value': 'UNMOUNTED' }, 'serialNo': 'SOME_SERIAL', 'shortSerialNo': 'SOME_SERIAL' }, { 'characteristics': { 'capabilities': [ 'INSIDE_TEMPERATURE_MEASUREMENT', 'IDENTIFY'] }, 'connectionState': { 'timestamp': '2017-02-20T18:33:49.092Z', 'value': True }, 'currentFwVersion': '36.15', 'deviceType': 'VA01', 'mountingState': { 'timestamp': '2017-02-12T13:34:35.288Z', 'value': 'CALIBRATED'}, 'serialNo': 'SOME_SERIAL', 'shortSerialNo': 'SOME_SERIAL' }, { 'characteristics': { 'capabilities': [ 'INSIDE_TEMPERATURE_MEASUREMENT', 'IDENTIFY'] }, 'connectionState': { 'timestamp': '2017-02-20T18:51:28.779Z', 'value': True }, 'currentFwVersion': '36.15', 'deviceType': 'VA01', 'mountingState': { 'timestamp': '2017-01-12T13:22:11.618Z', 'value': 'CALIBRATED' }, 'serialNo': 'SOME_SERIAL', 'shortSerialNo': 'SOME_SERIAL' } ]
Early start¶
-
class
libtado.api.Tado.get_early_start¶ Get the early start configuration of a zone.
Parameters: zone (int) – The zone ID. Returns: A dictionary with the early start setting of the zone. (True or False) Return type: dict Example
{ 'enabled': True }
Heating circuits¶
-
class
libtado.api.Tado.get_heating_circuits¶ Gets the heating circuits in the current home
Returns: list of all dictionaries for all heating circuits
Home¶
-
class
libtado.api.Tado.get_home¶ Get information about the home.
Returns: A dictionary with information about your home. Return type: dict Example
{ 'address': { 'addressLine1': 'SOME_STREET', 'addressLine2': None, 'city': 'SOME_CITY', 'country': 'SOME_COUNTRY', 'state': None, 'zipCode': 'SOME_ZIP_CODE' }, 'contactDetails': { 'email': 'SOME_EMAIL', 'name': 'SOME_NAME', 'phone': 'SOME_PHONE' }, 'dateTimeZone': 'Europe/Berlin', 'geolocation': { 'latitude': SOME_LAT, 'longitude': SOME_LONG }, 'id': SOME_ID, 'installationCompleted': True, 'name': 'SOME_NAME', 'partner': None, 'simpleSmartScheduleEnabled': True, 'temperatureUnit': 'CELSIUS' }
Home state¶
-
class
libtado.api.Tado.get_home_state¶ Get information about the status of the home.
Returns: A dictionary with the status of the home. Return type: dict
Incidents¶
-
class
libtado.api.Tado.get_incidents¶ Gets the ongoing incidents in the current home
Returns: Incident information Return type: dict
Installations¶
-
class
libtado.api.Tado.get_installations¶ Gets the ongoing installations in the current home
Returns: list of all current installations
Invitations¶
-
class
libtado.api.Tado.get_invitations¶ Get active invitations.
Returns: A list of active invitations to your home. Return type: list Example
[ { 'email': 'SOME_INVITED_EMAIL', 'firstSent': '2017-02-20T21:01:44.450Z', 'home': { 'address': { 'addressLine1': 'SOME_STREET', 'addressLine2': None, 'city': 'SOME_CITY', 'country': 'SOME_COUNTRY', 'state': None, 'zipCode': 'SOME_ZIP_CODE' }, 'contactDetails': { 'email': 'SOME_EMAIL', 'name': 'SOME_NAME', 'phone': 'SOME_PHONE' }, 'dateTimeZone': 'Europe/Berlin', 'geolocation': { 'latitude': SOME_LAT, 'longitude': SOME_LONG }, 'id': SOME_ID, 'installationCompleted': True, 'name': 'SOME_NAME', 'partner': None, 'simpleSmartScheduleEnabled': True, 'temperatureUnit': 'CELSIUS' }, 'inviter': { 'email': 'SOME_INVITER_EMAIL', 'enabled': True, 'homeId': SOME_ID, 'locale': 'SOME_LOCALE', 'name': 'SOME_NAME', 'type': 'WEB_USER', 'username': 'SOME_USERNAME' }, 'lastSent': '2017-02-20T21:01:44.450Z', 'token': 'SOME_TOKEN' } ]
Me¶
-
class
libtado.api.Tado.get_me¶ Get information about the current user.
Returns: A dictionary with information about the current user. Return type: dict Example
{ 'email': 'SOME_EMAIL', 'homes': [ { 'id': SOME_ID, 'name': 'SOME_NAME' } ], 'locale': 'en_US', 'mobileDevices': [], 'name': 'SOME_NAME', 'username': 'SOME_USERNAME', 'secret': 'SOME_CLIENT_SECRET' }
Measuring device¶
-
class
libtado.api.Tado.get_measuring_device¶ Gets the active measuring device of a zone
Parameters: zone (int) – The zone ID. Returns: A dictionary with the current measuring informations. Return type: dict
Open window detection¶
-
class
libtado.api.Tado.set_open_window_detection¶ Get the open window detection for a zone
Parameters: - zone (int) – The zone ID.
- enabled (bool) – If open window detection is enabled
- seconds (int) – timeout in seconds
Report¶
-
class
libtado.api.Tado.get_report¶ Parameters: - zone (int) – The zone ID.
- date (str) – The date in ISO8601 format. e.g. “2019-02-14”
Returns: The daily report.
Return type: dict
Schedule Timetables¶
-
class
libtado.api.Tado.get_schedule_timetables¶ Gets the schedule timetables supported by the zone
Parameters: zone (int) – The zone ID. Returns: The schedule types Return type: dict
Schedule¶
-
class
libtado.api.Tado.get_schedule¶ Get the type of the currently configured schedule of a zone.
Parameters: zone (int) – The zone ID. Returns: A dictionary with the ID and type of the schedule of the zone. Return type: dict Tado allows three different types of a schedule for a zone:
- The same schedule for all seven days of a week.
- One schedule for weekdays, one for saturday and one for sunday.
- Seven different schedules - one for every day of the week.
Example
{ 'id': 1, 'type': 'THREE_DAY' }
Schedule blocks¶
-
class
libtado.api.Tado.get_schedule_blocks¶ Gets the blocks for the current schedule on a zone
Parameters: - zone (int) – The zone ID.
- schedule (int) – The schedule ID to fetch
Returns: The blocks for the requested schedule
Return type: list
State¶
-
class
libtado.api.Tado.get_state¶ Get the current state of a zone including its desired and current temperature. Check out the example output for more.
Parameters: zone (int) – The zone ID. Returns: A dictionary with the current settings and sensor measurements of the zone. Return type: dict Example
{ 'activityDataPoints': { 'heatingPower': { 'percentage': 0.0, 'timestamp': '2017-02-21T11:56:52.204Z', 'type': 'PERCENTAGE' } }, 'geolocationOverride': False, 'geolocationOverrideDisableTime': None, 'link': {'state': 'ONLINE'}, 'overlay': None, 'overlayType': None, 'preparation': None, 'sensorDataPoints': { 'humidity': { 'percentage': 44.0, 'timestamp': '2017-02-21T11:56:45.369Z', 'type': 'PERCENTAGE' }, 'insideTemperature': { 'celsius': 18.11, 'fahrenheit': 64.6, 'precision': { 'celsius': 1.0, 'fahrenheit': 1.0 }, 'timestamp': '2017-02-21T11:56:45.369Z', 'type': 'TEMPERATURE' } }, 'setting': { 'power': 'ON', 'temperature': { 'celsius': 20.0, 'fahrenheit': 68.0 }, 'type': 'HEATING' }, 'tadoMode': 'HOME' }
Temperature offset¶
-
class
libtado.api.Tado.get_temperature_offset¶ Gets the temperature offset of a device
Returns: A dictionary that returns the offset in ‘celsius’ and ‘fahrenheit’ Return type: dict Example
{ "celsius": 0.0, "fahrenheit": 0.0 }
Weather¶
-
class
libtado.api.Tado.get_weather¶ Get the current weather of the location of your home.
Returns: A dictionary with weather information for your home. Return type: dict Example
{ 'outsideTemperature': { 'celsius': 8.49, 'fahrenheit': 47.28, 'precision': { 'celsius': 0.01, 'fahrenheit': 0.01 }, 'timestamp': '2017-02-21T12:06:11.296Z', 'type': 'TEMPERATURE' }, 'solarIntensity': { 'percentage': 58.4, 'timestamp': '2017-02-21T12:06:11.296Z', 'type': 'PERCENTAGE' }, 'weatherState': { 'timestamp': '2017-02-21T12:06:11.296Z', 'type': 'WEATHER_STATE', 'value': 'CLOUDY_PARTLY' } }
Zones¶
-
class
libtado.api.Tado.get_zones¶ Get all zones of your home.
Returns: A list of dictionaries with all your zones. Return type: list Example
[ { 'dateCreated': '2016-12-23T15:53:43.615Z', 'dazzleEnabled': True, 'deviceTypes': ['VA01'], 'devices': [ { 'characteristics': { 'capabilities': [ 'INSIDE_TEMPERATURE_MEASUREMENT', 'IDENTIFY'] }, 'connectionState': { 'timestamp': '2017-02-21T14:22:45.913Z', 'value': True }, 'currentFwVersion': '36.15', 'deviceType': 'VA01', 'duties': ['ZONE_UI', 'ZONE_DRIVER', 'ZONE_LEADER'], 'mountingState': { 'timestamp': '2017-02-12T13:34:35.288Z', 'value': 'CALIBRATED' }, 'serialNo': 'SOME_SERIAL', 'shortSerialNo': 'SOME_SERIAL' } ], 'id': 1, 'name': 'SOME_NAME', 'reportAvailable': False, 'supportsDazzle': True, 'type': 'HEATING' }, { 'dateCreated': '2016-12-23T16:16:11.390Z', 'dazzleEnabled': True, 'deviceTypes': ['VA01'], 'devices': [ { 'characteristics': { 'capabilities': [ 'INSIDE_TEMPERATURE_MEASUREMENT', 'IDENTIFY'] }, 'connectionState': { 'timestamp': '2017-02-21T14:19:40.215Z', 'value': True }, 'currentFwVersion': '36.15', 'deviceType': 'VA01', 'duties': ['ZONE_UI', 'ZONE_DRIVER', 'ZONE_LEADER'], 'mountingState': { 'timestamp': '2017-01-12T13:22:11.618Z', 'value': 'CALIBRATED' }, 'serialNo': 'SOME_SERIAL', 'shortSerialNo': 'SOME_SERIAL' } ], 'id': 3, 'name': 'SOME_NAME ', 'reportAvailable': False, 'supportsDazzle': True, 'type': 'HEATING' } ]
Setter¶
Early start¶
-
class
libtado.api.Tado.set_early_start¶ Enable or disable the early start feature of a zone.
Parameters: - zone (int) – The zone ID.
- enabled (bool) – Enable (True) or disable (False) the early start feature of the zone.
Returns: The new configuration of the early start feature.
Return type: dict
Example
{'enabled': True}
Home state¶
-
class
libtado.api.Tado.set_home_state¶ Set at-home/away state
Parameters: at_home (bool) – True for at HOME, false for AWAY.
Schedule¶
-
class
libtado.api.Tado.set_schedule¶ Set the type of the currently configured schedule of a zone.
Parameters: - zone (int) – The zone ID.
- schedule (int) –
The schedule to activate. The supported zones are currently
- 0: ONE_DAY
- 1: THREE_DAY
- 2: SEVEN_DAY
But the actual mapping should be retrieved via get_schedule_timetables.
Returns: The new configuration
Return type: dict
Schedule blocks¶
-
class
libtado.api.Tado.set_schedule_blocks¶ Sets the blocks for the current schedule on a zone
Parameters: - zone (int) – The zone ID.
- schedule (int) – The schedule ID.
- blocks (list) – The new blocks
Returns: The new configuration
Return type: list
Temperature¶
-
class
libtado.api.Tado.set_temperature¶ Set the desired temperature of a zone.
Parameters: - zone (int) – The zone ID.
- temperature (float) – The desired temperature in celsius.
- termination (str/int) – The termination mode for the zone.
Returns: A dictionary with the new zone settings.
Return type: dict
If you set a desired temperature less than 5 celsius it will turn of the zone!
The termination supports three different mode:
- “MANUAL”: The zone will be set on the desired temperature until you change it manually.
- “AUTO”: The zone will be set on the desired temperature until the next automatic change.
- INTEGER: The zone will be set on the desired temperature for INTEGER seconds.
Example
{ 'setting': { 'power': 'ON', 'temperature': {'celsius': 12.0, 'fahrenheit': 53.6}, 'type': 'HEATING' }, 'termination': { 'projectedExpiry': None, 'type': 'MANUAL' }, 'type': 'MANUAL' }
Temperature offset¶
-
class
libtado.api.Tado.set_temperature_offset¶ Sets the temperature offset of a device
Parameters: - device_serial (Str) – The serial number of the device
- offset (float) – the temperature offset to apply in celsius
Returns: A dictionary that returns the offset in ‘celsius’ and ‘fahrenheit’
Return type: dict