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.
Current operational status	Whether the associated HVAC system is currently heating or cooling, whether the fan is currently running.
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 activate and 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)

Request:

# 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"
  }'

Response:

{
  "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
}

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

Ruby

Request:

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

Response:

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

PHP

Request:

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

Response:

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

C#

Request:

// Coming soon!

Response:

// Coming soon!

---

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)

Request:

# 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"
}'

Response:

{
  "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
}

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

Ruby

Request:

# Coming soon!

Response:

# Coming soon!

PHP

Request:

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

Response:

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

C#

Request:

// Coming soon!

Response:

// Coming soon!