Thermostat

The Nest Learning Thermostat™ is an Internet-connected device that is intuitive and easy to use, continuously learning about usage patterns in the home to optimize comfort and save energy. Users can control their heating and cooling anywhere they have access to an Internet connection.

Supporting these features requires a sophisticated control system that goes above and beyond simple setpoint-based programs. Nest provides a wide range of algorithms (like Early On, True Radiant, Airwave™) that require a significant amount of computational power compared to most thermostats. The Nest Thermostat has the power needed to provide these advanced features.

The Nest API is designed to allow products to control the HVAC system without disrupting Nest algorithms or surprising the user with unexpected behaviors. They provide access to the following data for the Nest Thermostat:

• Structure name and device "where name" (location in the home)
• Custom thermostat label
• Online status and last connection information
• Current and target temperatures
• Temperature mode
• Eco Temperatures
• Time-to-Temperature
• Temperature scale (set F/C)
• Temperature Lock status, and if locked, the min/max locked temperature values
• Fan timer duration and HVAC mode
• Humidity
• Sunblock

Thermostat permissions

For read access to all Thermostat API data values, select the Thermostat read permission for your client.

For read access to all Thermostat API data values and additional write access to select values, select the Thermostat read/write permission for your client. This permission level allows you to update the following:

• Target temperature
• HVAC mode
• Fan timers

Starting with Thermostat read/write v5, you can also update the following:

• Temperature scale
• Thermostat label

Thermostat identifiers

Device

Nest devices are listed by type as an array of IDs, which can be used to uniquely identify a device via the device path. So a thermostat ID of "peyiJNo..." means that you can load the thermostat device model at devices/thermostats/peyiJNo... via the API.

When a device is connected to multiple products, each developer will see a different ID for that device. For a device that has installed multiple products from the same developer, the developer will see the same ID.

Name

Two name attributes are provided. The shorter name attribute is displayed in user interface labels, while name_long is used in long form text.

name

In these examples, name is "Hallway" or "Hallway (West)".

 

name_long

In this example, name_long is "Office (Upstairs)".

Label

Beginning with permissions version v5, you can add a custom thermostat label through the API. In the Nest app, label appears in parentheses, after the where name.

Beginning with permissions version v6, you can also read the Thermostat label.

Where

where_id

• A unique, Nest-generated identifier that represents name
• where_id is read-only, and is created automatically in the call to create a custom where name

Learn more about where names for Nest Thermostats, Nest Protects and Nest Cams.

where_name

When you choose any of the Thermostat permissions, you can access the device where_name from the device object (devices/thermostats).

Other metadata

All data values are read only, unless otherwise specified.

Data Value	Description
locale	The language and country code assigned to this device
software_version	A string that represents the firmware currently installed on the device
structure_id	A string that uniquely represents this structure; this is the structure that the device is paired with
last_connection	The timestamp of the last successful connection to the Nest service
is_online	Online status. This is determined by Nest using the last_connection time and an expected reconnection window that is device-specific.

Thermostat features

Thermostat modes

HVAC systems have four "on" states (heat, cool, heat-cool, eco) and one "off" state (off). We use these states to manage comfort and energy savings through hvac_mode and temperature data values.

• When Heat or Cool mode (heat, cool) is selected, the Thermostat adjusts the home to the target temperature.
• When Heat • Cool mode (heat-cool) is selected, the Thermostat will keep the home comfortable, within a preferred temperature range.
• When Eco Temperatures (eco) is selected, the Thermostat will apply energy-saving algorithms to keep the house comfortable and reduce energy usage. Thermostats in this mode display ECO.

Structures have two states related to presence: Home or Away. When no motion is sensed in the house, the structure will change from Home to Away, and the Thermostats in the home will enable Eco Temperatures automatically.

How hvac_mode and temperature values work together

Depending on the value of hvac_mode, only certain temperature data values can be accessed in the API:

HVAC mode	Temperature data values you can access
heat or cool	target_temperature_f or target_temperature_c
heat-cool	target_temperature_low_f and target_temperature_high_f   or target_temperature_low_c and target_temperature_high_c
eco	eco_temperature_low_f and eco_temperature_high_f   or eco_temperature_low_c and eco_temperature_high_c
off	none

In some scenarios, there are special rules around changing hvac_mode:

Scenario	Can hvac_mode be changed?
Temperature Lock is enabled	Yes
Emergency Shutoff is active	No
Emergency Heat is enabled	No
can_cool or can_heat value is false	No

Eco Temperatures

Eco Temperatures allow the user to save energy, whether they are home or not. Consider switching the hvac_mode to eco when implementing energy-saving behaviors in your product.

Eco Temperature endpoints are available in the Nest API beginning with Thermostat read and read/write v6 permissions.

Switching between eco and non-eco modes

Your product should not need to manage target temperatures directly in Eco mode. When the home is set to away, the target temp is not displayed, but is internally set, based on user selection. When the thermostat is set to OFF, then no target temperatures are observed.

If you absolutely must change target temperatures directly, be sure to make the change in two separate calls:

1. Change hvac_mode to any other value except eco
2. Modify the appropriate target_temperature data values

Beginning with Thermostat read and read/write v6 permissions, you can access previous_hvac_mode through the API to assist with HVAC mode transitions. previous_hvac_mode is used to store the hvac_mode of the device before it transitioned to "eco".

For example, if the Nest Thermostat is using Eco Temperatures (hvac_mode = "eco"), previous_hvac_mode is available, and you want your product to set target_temperature, then you must first:

1. get previous_hvac_mode
2. set hvac_mode to the previous_hvac_mode value
3. confirm hvac_mode is no longer set to "eco"

After these steps, set the target temperatures as appropriate.

Depending on the hvac_mode value, this is how previous_hvac_mode changes:

When hvac_mode state is...	Then, previous_hvac_mode can be...
eco	heat, cool, heat-cool or off
heat, cool, heat-cool or off	blank/empty

Target temperature

Target temperature is the most important value for the HVAC system - it's the desired temperature, typically set by the user. Most actions and decisions are based on it. From the API, Works with Nest products can write the target temperature as part of a larger process.

There is always a target temperature set when the system is on.

• When Heat or Cool mode (heat, cool) is selected, a single target_temperature is set
• When Heat • Cool mode (heat-cool) is selected, two target_temperature values are set, denoting a target range, a higher one for cooling and a lower one for heating
• When Eco mode (eco) is selected, the target temperature range is internally set

There are also safety temperatures that are a backstop to prevent freezing pipes or excessively high temperatures in the home.

When the Thermostat is OFF, no target temperatures are set.

Time-to-Temperature

Time-to-Temperature gives you access to these data values for the HVAC system:

• time_to_target - The time, in minutes, that it will take for the structure to reach the target temperature
• time_to_target_training
  • Training status
  • As the Thermostat learns how the HVAC system responds, it adjusts the estimate for reaching the target temperature
  • When the Thermostat is reasonably sure of the time estimate to reach the target temperature, status will change from training to ready

Ambient temperature

The temperature measured near the thermostat. Display the value that corresponds with the user's preferred temperature scale.

Temperature scale

The ambient and target temperature variables are organized by Celsius or Fahrenheit scale. The temperature_scale attribute will be either "F" or "C", depending on user preference. This property is set by each thermostat, so it is possible that in a single structure a user might have two thermostats, one in each temperature scale. Keep user preferences in mind when displaying temperature values.

Beginning with permissions version v5, you can change the temperature scale through the API.

Target and Ambient Temperature fields have _f and _c variants to accommodate consistent rounding when displaying temperatures.

Temperature display

When you display target temperature information, consider these three dependent values: temperature_scale, hvac_mode, and the structure's away state.

Many data values work together to determine what's shown on the Nest Thermostat display, and how it behaves.

• When hvac_mode is set to heat-cool, the Nest Thermostat displays the low and high setpoints separated by a bullet character (•), otherwise the Nest Thermostat displays just the target temperature
• When hvac_mode is set to off, the word "OFF" is displayed on the Nest Thermostat, in the user's preferred language
• When hvac_mode is set to eco, the word "ECO" is displayed on the Nest Thermostat, in the user's preferred language

The display temperature format also depends on the selected temperature scale (F/C).

Fahrenheit temperatures are displayed as whole numbers:

• Target temperature: 55°F
• Ambient temperature: 62°F

Celsius temperatures are displayed as a whole number or a decimal value, with the last digit set to ".5":

• Target temperature: 12°C
• Ambient temperature: 16.5°C

Leaf

When the leaf icon is showing on the front of the thermostat, the thermostat is set to an energy-saving temperature, and has_leaf = true.

Temperature Lock

Users can lock a Nest Thermostat so that it can only be adjusted within a limited temperature range. Beginning with permissions version v5, you can see if Temperature Lock is enabled by checking is_locked, and if it is, read Temperature Lock min/max values through the API:

• locked_temp_min_f
• locked_temp_max_f
• locked_temp_min_c
• locked_temp_max_c

Lock temperatures must be specified in pairs, as maximum and minimum values, and can only be written if is_locked = true.

Humidity

Humidity, in percent (%) format, measured at the device, rounded to the nearest 5%.

Sunblock

Sunblock technology automatically adjusts the temperature on the Nest Thermostat to compensate for heat spikes that occur from direct sunlight on the unit.

These data values will tell you if Sunblock is enabled and/or actively correcting the temperature.

• sunlight_correction_enabled
  • boolean, returns true if Sunblock is enabled
• sunlight_correction_active - boolean, returns true if Sunblock is active, indicating that the Thermostat is located in direct sunlight

Fan

Many HVAC systems have integrated fans, which means that the fan cannot be controlled independently. There is no off mode for integrated fans, because the fan needs to run when the heating or cooling is on.

However, if the HVAC system is compatible, the fan can be explicitly turned on via the API, in order to make occupants more comfortable, without engaging the full HVAC system.

If the fan can be controlled independently, has_fan will be set to true, and the following data values can be set with Thermostat read/write permissions:

• fan_timer_active - boolean, returns true if fan timer is engaged for a pre-programmed duration
• fan_timer_duration - int, the length of time (in minutes) that the fan is set to run

Use these values together to initiate the fan timer (turn the fan on) for a specific period of time. You can also use the fan_timer_timeout value to determine the timestamp of when the fan is set to stop running.

Note that you can always change fan_timer_duration - it is independent of hvac_mode or structure occupancy state (away).

You can expect these responses on success or fail:

• 200 OK
• 400 Bad Request

If the command to turn the fan on doesn't produce the expected result, it may be because the fan is already engaged (either manually by the user, or on a schedule, or because of an HVAC heat/cool cycle).

Rate limiting

We apply rate limiting to protect against excessive calls to devices, which may affect system or battery performance. Under normal conditions, Nest devices charge the battery from the low voltage wires on the heating and cooling system. But if excessive calls are made in a short period of time and the battery level gets low, the Nest Thermostat will turn off Wi-Fi to conserve power.

In practice, this means that we limit the number of calls that can be made to a device within a defined time period. If you exceed this limit, you'll receive an error response and a message indicating you've exceeded your limit.

For more information, see Data Rate Limits.

Power constraints

In some cases the Thermostat may not have enough battery power to service a modification request. In this case you will receive an error response and a message indicating the device can't service the request at this time. If this happens, give the battery some time to recharge before trying again.

Learn more about low battery conditions in the Nest Learning Thermostat.

Error messages

Some states render certain functions unavailable. These rules are in place to conserve energy or provide comfort and safety.

For information on what API call errors mean and how to handle them, see Error Messages.

Wi-Fi / connection issue

If a device is offline, modifications are not allowed. You can observe the online state of the device in the data model and display UI appropriately.