Creating Climate Setting Schedules

Learn how to configure climate setting schedules to set an HVAC mode setting and the desired temperature profile for a period of time in the future.

Seam enables you to create climate setting schedules on a smart thermostat. This functionality enables you to set future schedules for controlling the climate in users' homes or businesses automatically based on their needs. For example, a short-term-rental host can create—for each guest stay—a climate setting schedule that programs their thermostat with comfortable heating and cooling set points for the duration of the guest's stay.

You can create as many climate setting schedules as desired, as long as none of the schedules overlap. That is, only one climate setting schedule can be active at a time.

---

Climate Setting Schedules

Climate setting schedules enable you to program settings on a smart thermostat for specific periods of time. You can use this functionality to set schedules for controlling the climate in users' homes or businesses automatically based on their needs. For example, a short-term-rental host can create—for each guest stay—a climate setting schedule that programs their thermostat with comfortable heating and cooling set points for the duration of the guest's stay.

When a climate setting schedule becomes active, it overrides the default climate setting and becomes the current climate setting.

Settings in a Climate Setting Schedule

Climate setting schedules include a starting and ending date and time, as well as all the following climate settings:

• The HVAC mode

• Whether the automatic heating system is enabled

• Whether the automatic cooling system is enabled

• The corresponding set points in Fahrenheit or Celsius

• Whether to allow manual overrides of these settings

Climate Setting Schedule Constraints

Note the following constraints regarding climate setting schedules:

• Before you can create any climate setting schedules, you must first configure a default climate setting.

• You can create as many climate setting schedules as desired, as long as none of the schedules overlap. That is, only one climate setting schedule can be active at a time.

• When there are no active climate setting schedules, the thermostat falls back to the configured default climate setting.

---

Before You Begin

To confirm that Seam supports thermostat programming for your device, use Get Device or Get Thermostat to query the device and check its capabilities_supported property. Ensure that the capabilities_supported list includes thermostat. For more information, see Retrieving Individual Thermostats.

In addition, before you can create any climate setting schedules, you must first set the default climate setting for a thermostat.

---

Create a Climate Setting Schedule

To create a climate setting schedule, issue a Create Climate Setting Schedule request. In the body of the request, specify the following parameters:

Parameter	Type	Description
schedule_type	Enum Optional	Schedule type Default: time_bound
device_id	String Required	ID of the thermostat for which to create the new climate setting schedule
name	String Optional	Name of the climate setting schedule
schedule_starts_at	String Required	Date and time at which the climate setting schedule becomes active, as an ISO 8601 timestamp
schedule_ends_at	String Required	Date and time after which the climate setting schedule becomes inactive, as an ISO 8601 timestamp
automatic_heating_enabled	Boolean	Indicates whether the automatic heating system is enabled during the scheduled period If you specify automatic_heating_enabled, you must also specify heating_set_point_celsius or heating_set_point_fahrenheit. Also, if you specify automatic_heating_enabled, Seam automatically sets hvac_mode_setting accordingly.
automatic_cooling_enabled	Boolean	Indicates whether the automatic cooling system is enabled during the scheduled period If you specify automatic_cooling_enabled, you must also specify cooling_set_point_celsius or cooling_set_point_fahrenheit. Also, if you specify automatic_cooling_enabled, Seam automatically sets hvac_mode_setting accordingly.
hvac_mode_setting	Enum	HVAC mode for the scheduled period Values are heat, cool, heat_cool, and off. If you specify hvac_mode_setting, you must also specify one or more of cooling_set_point_celsius, heating_set_point_celsius, cooling_set_point_fahrenheit, and heating_set_point_fahrenheit, depending on the HVAC mode. Also, if you specify hvac_mode_setting, Seam automatically sets automatic_heating_enabled and automatic_cooling_enabled accordingly.
cooling_set_point_celsius	Number	Cooling set point in Celsius for the scheduled period This set point is relevant when hvac_mode_setting is cool or heat_cool (that is, when automatic_cooling_enabled is true).
heating_set_point_celsius	Number	Heating set point in Celsius for the scheduled period This set point is relevant when hvac_mode_setting is heat or heat_cool (that is, when automatic_heating_enabled is true).
cooling_set_point_fahrenheit	Number	Cooling set point in Fahrenheit for the scheduled period This set point is relevant when hvac_mode_setting is cool or heat_cool (that is, when automatic_cooling_enabled is true).
heating_set_point_fahrenheit	Number	Heating set point in Fahrenheit for the scheduled period This set point is relevant when hvac_mode_setting is heat or heat_cool (that is, when automatic_heating_enabled is true).
manual_override_allowed	Boolean Optional	Indicates whether to allow manual overrides of these settings during the scheduled period If true, a person can override the climate setting by making adjustments from the thermostat itself or from their app. If false, Seam makes sure that the climate setting is set on the thermostat every ten minutes. We recommend setting manual_override_allowed to true, unless you do not want anyone to change this thermostat setting.

Note that you configure either hvac_mode_setting or automatic_heating_enabled and automatic_cooling_enabled. When you configure hvac_mode_setting, Seam automatically configures automatic_heating_enabled and automatic_cooling_enabled correspondingly. Conversely, when you configure automatic_heating_enabled and automatic_cooling_enabled, Seam automatically configures hvac_mode_setting correspondingly. The following table shows this automatic mapping:

hvac_mode_setting	automatic_heating_enabled	automatic_cooling_enabled
heat	true	false
cool	false	true
heat_cool	true	true
off	false	false

Python

Request:

climate_setting_schedule = seam.thermostats.climate_setting_schedules.create(
    device = "518f692b-f865-4590-8c3e-3849e9984c75",
    name = "Guest 1 Stay",
    schedule_starts_at = "2023-12-10T15:00:00.000Z",
    schedule_ends_at = "2023-12-17T11:00:00.000Z",
    hvac_mode_setting = "heat_cool",
    cooling_set_point_celsius = 25,
    heating_set_point_celsius = 20,
    manual_override_allowed = True
)

pprint(climate_setting_schedule)

Response:

ClimateSettingSchedule(automatic_heating_enabled=True,
                       automatic_cooling_enabled=True,
                       hvac_mode_setting='heat_cool',
                       cooling_set_point_celsius=25.0,
                       heating_set_point_celsius=20.0,
                       cooling_set_point_fahrenheit=77.0,
                       heating_set_point_fahrenheit=68.0,
                       manual_override_allowed=True,
                       schedule_type='time_bound',
                       name='Guest 1 Stay',
                       schedule_starts_at='2023-12-10T15:00:00.000Z',
                       schedule_ends_at='2023-12-17T11:00:00.000Z',
                       climate_setting_schedule_id='b0a7fb2b-ef0a-43f5-908a-0564d2e86a67',
                       is_set_on_device=False,
                       device_id='518f692b-f865-4590-8c3e-3849e9984c75',
                       created_at='2023-11-19T09:15:25.107Z')

cURL (bash)

Request:

curl -X 'POST' \
  'https://connect.getseam.com/thermostats/climate_setting_schedules/create' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
  "name": "Guest 1 Stay",
  "schedule_starts_at": "2023-12-10T15:00:00.000Z",
  "schedule_ends_at": "2023-12-17T11:00:00.000Z",
  "hvac_mode_setting": "heat_cool",
  "cooling_set_point_celsius": 25,
  "heating_set_point_celsius": 20,
  "manual_override_allowed": true
}'

Response:

{
  "climate_setting_schedule": {
    "climate_setting_schedule_id": "c17d606a-fe7c-4345-a6d7-1bb4ab9b77f0",
    "schedule_type": "time_bound",
    "device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
    "name": "Guest 1 Stay",
    "schedule_starts_at": "2023-12-10T15:00:00.000Z",
    "schedule_ends_at": "2023-12-17T11:00:00.000Z",
    "automatic_heating_enabled": true,
    "automatic_cooling_enabled": true,
    "hvac_mode_setting": "heat_cool",
    "cooling_set_point_celsius": 25,
    "heating_set_point_celsius": 20,
    "cooling_set_point_fahrenheit": 77,
    "heating_set_point_fahrenheit": 68,
    "manual_override_allowed": true,
    "is_set_on_device": false,
    "created_at": "2023-11-19T09:10:17.395Z"
  },
  "ok": true
}

JavaScript

Request:

const climate_setting_schedule = await seam.thermostats.climateSettingSchedules.create({
  device_id: "518f692b-f865-4590-8c3e-3849e9984c75",
  name: "Guest 1 Stay",
  schedule_starts_at: "2023-12-10T15:00:00.000Z",
  schedule_ends_at: "2023-12-17T11:00:00.000Z",
  hvac_mode_setting: "heat_cool",
  cooling_set_point_celsius: 25,
  heating_set_point_celsius: 20,
  manual_override_allowed: true
})

console.log(climate_setting_schedule)

Response:

{
  climate_setting_schedule_id: '0232b54d-368b-483c-9b4e-36f139455e15',
  schedule_type: 'time_bound',
  device_id: '518f692b-f865-4590-8c3e-3849e9984c75',
  name: 'Guest 1 Stay',
  schedule_starts_at: '2023-12-10T15:00:00.000Z',
  schedule_ends_at: '2023-12-17T11:00:00.000Z',
  automatic_heating_enabled: true,
  automatic_cooling_enabled: true,
  hvac_mode_setting: 'heat_cool',
  cooling_set_point_celsius: 25,
  heating_set_point_celsius: 20,
  cooling_set_point_fahrenheit: 77,
  heating_set_point_fahrenheit: 68,
  manual_override_allowed: true,
  is_set_on_device: false,
  created_at: '2023-11-19T09:23:12.979Z'
}

C#

Request:

var deviceId = "518f692b-f865-4590-8c3e-3849e9984c75";
ClimateSettingSchedule climateSettingSchedule = seam.ClimateSettingSchedulesThermostats.Create(
      deviceId: deviceId,
      name: "Guest 1 Stay",
      scheduleStartsAt: "2023-12-10T15:00:00.000Z",
      scheduleEndsAt: "2023-12-17T11:00:00.000Z",
      hvacModeSetting: Seam.Api.ClimateSettingSchedulesThermostats.CreateRequest.HvacModeSettingEnum.HeatCool,
      coolingSetPointCelsius: 25,
      heatingSetPointCelsius: 20,
      manualOverrideAllowed: true
);
Console.WriteLine(climateSettingSchedule);

Response:

{
  "climate_setting_schedule_id": "c5da2ce6-7c72-45ee-9823-8f7ffd5f141a",
  "device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
  "name": "Guest 1 Stay",
  "schedule_starts_at": "2023-12-10T15:00:00.000Z",
  "schedule_ends_at": "2023-12-17T11:00:00.000Z",
  "created_at": "2023-11-20T07:19:06.862Z",
  "automatic_heating_enabled": true,
  "automatic_cooling_enabled": true,
  "hvac_mode_setting": "heat_cool",
  "cooling_set_point_celsius": 25,
  "heating_set_point_celsius": 20,
  "cooling_set_point_fahrenheit": 77,
  "heating_set_point_fahrenheit": 68,
  "manual_override_allowed": true
}

Java

Request:

var deviceId = "518f692b-f865-4590-8c3e-3849e9984c75";
var climateSettingSchedule = seam.thermostats().climateSettingSchedules()
            .create(ClimateSettingSchedulesCreateRequest.builder()
                    .deviceId(deviceId)
                    .scheduleStartsAt("2023-12-10T15:00:00.000Z")
                    .scheduleEndsAt("2023-12-17T11:00:00.000Z")
                    .hvacModeSetting(HvacModeSetting.HEAT_COOL)
                    .coolingSetPointCelsius(25.0)
                    .heatingSetPointCelsius(20.0)
                    .manualOverrideAllowed(true)
                    .name("Guest 1 Stay")
                    .build());
System.out.println(climateSettingSchedule);

Response:

{
  "climate_setting_schedule" : {
    "climate_setting_schedule_id" : "b7d5cc0c-defc-4af1-9448-85b96aff5fd6",
    "device_id" : "518f692b-f865-4590-8c3e-3849e9984c75",
    "name" : "Guest 1 Stay",
    "schedule_starts_at" : "2023-12-10T15:00:00.000Z",
    "schedule_ends_at" : "2023-12-17T11:00:00.000Z",
    "created_at" : "2023-11-19T09:52:36.855Z",
    "automatic_heating_enabled" : true,
    "automatic_cooling_enabled" : true,
    "hvac_mode_setting" : "heat_cool",
    "cooling_set_point_celsius" : 25.0,
    "heating_set_point_celsius" : 20.0,
    "cooling_set_point_fahrenheit" : 77.0,
    "heating_set_point_fahrenheit" : 68.0,
    "manual_override_allowed" : true,
    "schedule_type" : "time_bound",
    "schedule_type" : "time_bound",
    "is_set_on_device" : false
  },
  "ok" : true
}