Retrieving Thermostats

Learn how to retrieve all thermostats or a specific thermostat by ID.

When you use the /thermostats/list and /devices/get endpoints to retrieve information about your connected thermostats, the Seam API returns the following categories of information:

Category	Details
Current conditions	Current temperature in Fahrenheit and Celsius, current relative humidity, and so on. This includes such properties as temperature_celsius, temperature_fahrenheit, is_cooling, is_heating, is_fan_running, relative_humidity
Current operational status	Whether the associated HVAC system is currently heating or cooling, whether the fan is currently running. These properties are named current_climate_setting and reflect what the thermostat is set to 'achieve'.
Available HVAC modes for the thermostat	heat, cool, heat_cool, and off.
Available fan modes for the thermostat	on, auto, and circulate.
Thermostat capability flags	Capabilities of the thermostat—at a granular level. These capability flags include the following: device.can_hvac_heat device.can_hvac_cool device.can_hvac_heat_cool device.can_turn_off_hvac
Available climate presets	Climate presets that you can schedule on the thermostat.
Climate preset constraints	Constraints related to climate presets for the specific thermostat brand or model. For example, a thermostat might have a minimum or maximum cooling or heating set point or a minimum delta between the cooling and heating set points.

List All Thermostats

To retrieve all thermostats, issue a /thermostats/list request. You can filter by a variety of criteria, including connected_account_id, connect_webview_id, manufacturer, user_identifier_key, and so on.

The following example retrieves all Google Nest thermostats:

JavaScript

Request:

await seam.thermostats.list({
  manufacturer: "nest"
});

Response:

[
  {
    device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
    device_type: 'nest_thermostat',
    properties: {
      online: true,
      is_cooling: false,
      is_heating: false,
      manufacturer: 'nest',
      is_fan_running: false,
      relative_humidity: 0.46,
      temperature_celsius: 24.64,
      temperature_fahrenheit: 76.352,
      available_hvac_mode_settings: [
        'heat',
        'cool',
        'heat_cool',
        'off'
      ],
      current_climate_setting: {
        display_name: 'eco',
        hvac_mode_setting: 'heat_cool',
        manual_override_allowed: true,
        cooling_set_point_celsius: 25,
        cooling_set_point_fahrenheit: 77,
        heating_set_point_celsius: 20,
        heating_set_point_fahrenheit: 68
      },
      ...
    },
    can_hvac_cool: true,
    can_hvac_heat: true,
    can_turn_off_hvac: true,
    can_hvac_heat_cool: true,
    ...
  },
  ...
]

cURL

Python

Ruby

PHP

C#

---

Get an Individual Thermostat

To get a specific thermostat, issue a /devices/get request, including the desired device_id.

JavaScript

Request:

await seam.devices.get({
  device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
});

Response:

{
  device_id: 'a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  device_type: 'nest_thermostat',
  properties: {
    online: true,
    is_cooling: false,
    is_heating: false,
    manufacturer: 'nest',
    is_fan_running: false,
    relative_humidity: 0.46,
    temperature_celsius: 24.64,
    temperature_fahrenheit: 76.352,
    current_climate_setting: [Object],
    available_hvac_mode_settings: [
      'heat',
      'cool',
      'heat_cool',
      'off'
    ],
    current_climate_setting: {
      display_name: 'eco',
      hvac_mode_setting: 'heat_cool',
      manual_override_allowed: true,
      cooling_set_point_celsius: 25,
      cooling_set_point_fahrenheit: 77,
      heating_set_point_celsius: 20,
      heating_set_point_fahrenheit: 68
    },
    ...
  },
  can_hvac_cool: true,
  can_hvac_heat: true,
  can_turn_off_hvac: true,
  can_hvac_heat_cool: true,
  ...
}

cURL

Python

Ruby

PHP

C#