Skip to main content
Use Seam to connect a Tado account, list its rooms as thermostats, set a room’s HVAC mode and set point, and schedule climate presets. Tado supports heat, cool, and off only, and each room reports its own capabilities. Check the Tado-specific restrictions before you build. For real thermostats, complete the Tado setup guide first. Create a Seam account and get an API key to try virtual Tado thermostats in a sandbox workspace.

Step 1: Install a Seam SDK

Seam provides client libraries for many languages, including JavaScript, Python, Ruby, PHP, and others, as well as a Postman collection and an OpenAPI spec. First, install a Seam SDK, as follows:
The Java examples in this guide use the HTTP client built into Java 11 and later, so they need no extra package. Next, go to https://console.seam.co/ and sign up for Seam to get your API key. Then, export your API key as an environment variable.
This guide uses a sandbox workspace. You can only connect virtual devices and systems in this type of workspace. If you want to connect a real Tado thermostat, use a non-sandbox workspace and API key.

To control your Tado thermostats using the Seam API, you must first authorize your Seam workspace to connect to your Tado account. If your application needs to connect to your users’ Tado accounts, Seam provides fully-embedded, customizable client-side Connect Webviews to collect their authorization securely. Tado doesn’t let other apps collect a Tado password. Instead, the Connect Webview shows a link and a short code. Your user opens the link, signs in to Tado on Tado’s own site, and approves Seam there. The Connect Webview then finishes on its own.
This guide shows you how to create a Connect Webview programmatically using the Seam API.The Seam Console provides another easy way to connect devices to your Seam workspace.Go to https://console.seam.co/. On the Devices page, click + Add Devices. Then, see Authorize your workspace in this guide to complete the Connect Webview authorization flow.

Create a Connect Webview

Create a connect_webview object and then note the returned URL. The C#, Java, and Go examples in this guide send requests to the Seam API directly. The Java and Go examples define a small seamPost helper here, and later steps reuse it. Code:
Output:

Authorize Your Workspace

In a web browser, go to the URL that the Connect Webview object returned. For application developers, you can redirect your user to this Connect Webview URL so that they can authorize your app to control their devices using Seam. We even provide a prebuilt Connect Account Button within our suite of Seam Components that help you build your device management flow.
Because you’re using a sandbox workspace, you connect Seam’s test Tado account. We provide virtual devices for each of the brands that we support. These sandbox devices and systems enable you to test your app with devices from multiple brands without the need to own all the corresponding physical devices.
Complete the Connect Webview authorization flow, as follows:
  1. In the Connect Webview, select Open tado. In a sandbox workspace, this link opens a sandbox approval page, which connects the Tado sandbox account right away. You don’t need to sign in.
  2. Return to the Connect Webview. It continues on its own within a few seconds. You can also select I’ve approved Seam in tado.
Confirm that authorization through the Connect Webview was successful by querying its status. Code:
Output:

Step 3: Retrieve Tado thermostat devices

When you link a Tado account with Seam, we create a device object for each heating room and each Smart AC Control room in the account. Hot water rooms don’t appear. You can retrieve these devices using the List Devices and Get Device endpoints. The device’s device_type is tado_thermostat, and properties.tado_metadata identifies the Tado home and room. The device also reports the room’s temperature and humidity, its current climate setting, its supported HVAC modes, and its set point range. Code:
Output:

Step 4: Control your Tado thermostat

Each device that you connect to Seam has a specific set of capabilities. Capability flags tell your application what each device supports. For Tado, check can_hvac_heat and can_hvac_cool before you send a command: a heating room supports heat and off, and a Smart AC Control room supports cool, off, and usually heat. Try out the following actions on your Tado thermostat:

Set the HVAC mode

To set the HVAC mode, use any of the following endpoints or their equivalents in the Seam SDKs:
  • /thermostats/heat
  • /thermostats/cool
  • /thermostats/off
  • /thermostats/set_hvac_mode
Specify the thermostat that you want to control by including the device_id in the request body. Also, include the desired temperature set point. The set point must be within the room’s range, such as min_heating_set_point_celsius and max_heating_set_point_celsius. In this example, set the Living Room to heat with a heating set point of 21 °C. Each of these HVAC mode endpoints returns an action attempt to track the progress of the operation. Code:
Output:
The JavaScript, Python, Ruby, and PHP SDKs wait for the action attempt to finish. The C#, Java, Go, cURL, and Seam CLI examples return the action attempt right away, with status set to pending. To follow it, poll Get Action Attempt until its status is success or error.

Verify the change

Confirm that the action attempt succeeded, then get the device and read properties.current_climate_setting. Its hvac_mode_setting and heating_set_point_celsius show what Tado reports for the room. properties.temperature_celsius is the room’s measured temperature, not the set point. Code:
Output:
If the reported settings don’t match yet, Seam may not have read the room since the change. Get the device again after a short wait, or listen for thermostat events instead of retrying the command. A failed command can also mean that the Tado account has used up its daily API allowance. For details, see Sync Frequency and API Limits. If you test a real thermostat, record its original mode and set point and restore them after the test. The setting you apply through Seam stays in place until the next change, and the room’s own Tado schedule doesn’t take over again on its own.

Create and schedule climate presets

You can use the Seam API to create climate presets for Tado thermostats. Each climate preset is a saved group of settings, such as the HVAC mode and set point. For example, you could create a comfort preset for when a vacation rental is occupied and an eco preset for when it’s empty. You can schedule climate presets to start and stop whenever you’d like, and set a fallback climate preset that applies outside your schedules. Because Tado doesn’t support fan modes, leave out fan_mode_setting when you create a Tado climate preset. In this example, create comfort and eco presets for the Living Room, set eco as the fallback, and schedule the comfort preset for a guest’s stay. Code:
For more about presets and schedules, see Creating and Managing Climate Presets and Creating and Managing Thermostat Schedules.

Step 5: Connect a real Tado thermostat

Now that you have learned the basics of using the Seam API, you can connect and control a real Tado thermostat. To do so, switch to a non-sandbox workspace and API key. For the steps your users follow to approve Seam in Tado, see the Tado setup guide.

Step 6: Build your application!

The Seam API and Seam SDKs give you up-to-date information about your thermostats. Seam also sends thermostat-related events that let you monitor your thermostats and the connected heating and cooling systems. Our simulation endpoints help you test your app against events that are hard to reproduce with real devices.

Next steps

Now that you’ve completed this getting started guide for Tado devices, you can learn more about what you can do with the Seam API.
If you have any questions or want to report an issue, email us at support@seam.co.

seam-api-key

Get an API Key (free)

Sign up for the Seam Console and get your API keys. →
seam-contact-us-light

Contact Sales

Got a project or a specific question? Contact our team to get answers. →