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:

Python

Request:

seam.thermostats.list(
  manufacturer = "nest"
)

Response:

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

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Get an Individual Thermostat

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

Python

Request:

seam.devices.get(
  device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
)

Response:

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

cURL (bash)

JavaScript

Ruby

PHP

C#