Retrieving Thermostats

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 heatingset pointor aminimum deltabetween 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: Request:

await seam.thermostats.list({
  manufacturer: 'nest',
})

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/thermostats/list' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "manufacturer": "nest"
  }'

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

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

$seam->thermostats->list(
  manufacturer: "nest"
);

// Coming soon!

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,
    ...
  },
  ...
]

{
  "thermostats": [
    {
      "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
      "device_type": "nest_thermostat",
      "properties": {
        "online": true,
        "is_cooling": false,
        "is_heating": false,
        "is_fan_running": false,
        "manufacturer": "nest",
        "relative_humidity": 0.46,
        "temperature_celsius": 24.64,
        "temperature_fahrenheit": 76.352,
        "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
        },
        "available_hvac_mode_settings": [
          "heat",
          "cool",
          "heat_cool",
          "off"
        ],
        ...
      },
      "can_hvac_cool": true,
      "can_hvac_heat": true,
      "can_turn_off_hvac": true,
      "can_hvac_heat_cool": true,
      ...
    },
    ...
  ],
  "ok": true
}

[
  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,
      ...
    },
    ...
  ),
  ...
]

[
  <Seam::Resources::Device:0x005f0
    device_id="a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
    device_type="nest_thermostat"
    properties=#<Seam::DeepHashAccessor:0x0000016b1791f068 @data={
      "online"=>true,
      "is_cooling"=>false,
      "is_heating"=>false,
      "manufacturer"=>"nest",
      "is_fan_running"=>false,
      "relative_humidity"=>0.36,
      "temperature_celsius"=>21.11111111111111,
      "temperature_fahrenheit"=>70,
      "available_hvac_mode_settings"=>[
        "heat",
        "cool",
        "heat_cool",
        "off"
      ],
      "current_climate_setting"=>{
        "climate_preset_key"=>"unoccupied",
        "can_edit"=>true,
        "can_delete"=>true,
        "display_name"=>"unoccupied",
        "fan_mode_setting"=>"auto",
        "hvac_mode_setting"=>"heat_cool",
        "manual_override_allowed"=>true,
        "cooling_set_point_celsius"=>30,
        "heating_set_point_celsius"=>15,
        "cooling_set_point_fahrenheit"=>86,
        "heating_set_point_fahrenheit"=>59
      },
      ...
    }>
    can_hvac_cool=true
    can_hvac_heat=true
    can_turn_off_hvac=true
    can_hvac_heat_cool=true
    ...
  >,
  ...
]

[
  {
    "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": {
      "manufacturer": "nest",
      "online": true,
      "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,
      "relative_humidity": 0.46,
      "temperature_celsius": 24.64,
      "temperature_fahrenheit": 76.352,
      ...
    },
    ...
  },
  ...
]

// Coming soon!

Get an Individual Thermostat

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

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

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/devices/get' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
}'

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

# Coming soon!

$seam->devices->get(
  device_id: "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
);

// Coming soon!

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

{
  "device": {
    "device_id": "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
    "device_type": "nest_thermostat",
    "properties": {
      "online": true,
      "is_cooling": false,
      "is_heating": false,
      "is_fan_running": false,
      "manufacturer": "nest",
      "relative_humidity": 0.46,
      "temperature_celsius": 24.64,
      "temperature_fahrenheit": 76.352,
      "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
      },
      "available_hvac_mode_settings": [
        "heat",
        "cool",
        "heat_cool",
        "off"
      ],
      ...
    },
    "can_hvac_cool": true,
    "can_hvac_heat": true,
    "can_turn_off_hvac": true,
    "can_hvac_heat_cool": true,
    ...
  },
  "ok": true
}

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,
    ...
  },
  ...
)

# Coming soon!

{
  "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": {
    "manufacturer": "nest",
    "online": true,
    "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,
    "relative_humidity": 0.46,
    "temperature_celsius": 24.64,
    "temperature_fahrenheit": 76.352,
    ...
  },
  ...
}

// Coming soon!

Getting Started

Use Cases

Core Concepts

Capability Guides

UI Components

Developer Tools

Industry Guides

Device Manufacturer Guidance

Low-Level APIs

Retrieving Thermostats

List All Thermostats

Get an Individual Thermostat

​List All Thermostats

​Get an Individual Thermostat

List All Thermostats

Get an Individual Thermostat