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
- Temperature scale (set F/C)
- Temperature Lock status, and if locked, the min/max locked temperature values
- Fan timer duration and HVAC mode
For read access to all Thermostat API data values, select the Thermostat read permission in your product.
For read access to all Thermostat API data values and additional write access to select values, select the Thermostat read/write permission in your product. 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
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.
Two name attributes are provided. The shorter
name attribute is displayed in
user interface labels, while
name_long is used in long form text.
In these examples,
name is "Hallway" or "Hallway (West)".
In this example,
name_long is "Office (Upstairs)".
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.
- A unique, Nest-generated identifier that represents
- Use this value with the
$companyobject to send resource use data
where_idis read-only, and is created automatically in the call to create a custom where
When you choose any of the
you can access the device
where_name from the device object
All data values are read only, unless otherwise specified.
||The language and country code assigned to this device|
||A string that represents the firmware currently installed on the device|
||A string that uniquely represents this structure; this is the structure that the device is paired with|
||The timestamp of the last successful connection to the Nest service|
||Online status. This is determined by Nest using the
HVAC systems have four "on" states (
eco) and one
"off" state (
off). We use these states to manage comfort and energy savings
hvac_mode and temperature data values.
- When Heat or Cool mode (
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, instead of AWAY or AUTO-AWAY.
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.
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|
In some scenarios, there are special rules around changing
|Temperature Lock is enabled||Yes|
|Emergency Shutoff is active||No|
|Emergency Heat is enabled||No|
Beginning with permissions version v6, you can access Eco Temperature values through the API.
It can take some weeks for all devices to update, so API calls related to Eco Temperatures can fail with an error message if the device has not updated.
Multiple device software versions
In addition to device firmware updates, the Nest app must also be updated. Your users will likely have a mix of Nest app versions installed, so some calls will return data from the old data model, and others will return new data values. This can be true for devices in the same structure.
Your code should check that the Nest app
software_version >= 5.6. When this is
true, then you can use all the related
eco_temperature data values in your
product. All software versions
< 5.6 should assume that Eco Temperatures are
An alternate solution is to fail gracefully. You can set your product to allow the user to select Eco Temperatures, and send that request to the API. If the value is not supported, the API will reject the setting with an error message. You'll have to manage that error condition in your product and with appropriate messaging to your users.
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:
hvac_modeto any other value except
- Modify the appropriate
Beginning with Thermostat
permissions version v6,
you can also access
previous_hvac_mode through the API to assist with HVAC
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 (
previous_hvac_mode is available, and you want your product to set
target_temperature, then you must first:
hvac_modeis no longer set to "eco"
After these steps, set the target temperatures as appropriate.
Depending on the
hvac_mode value, this is how
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 (
cool) is selected, a single
- When Heat • Cool mode (
heat-cool) is selected, two
target_temperaturevalues 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 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
- 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
The temperature measured near the thermostat. Display the value that corresponds with the user's preferred 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
_c variants to accommodate
consistent rounding when displaying temperatures.
When you display target temperature information, consider these three
hvac_mode, and the structure's
Many data values work together to determine what's shown on the Nest Thermostat display, and how it behaves.
hvac_modeis 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
hvac_modeis set to
off, the word "OFF" is displayed on the Nest Thermostat, in the user's preferred language
hvac_modeis 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
When the leaf icon is showing on the front of the thermostat, the thermostat is
set to an energy-saving temperature, and
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
is enabled by checking
is_locked, and if it is,
read Temperature Lock min/max values through the API:
Lock temperatures must be specified in pairs, as maximum and minimum values, and
can only be written if
Humidity, in percent (%) format, measured at the device, rounded to the nearest 5%.
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.
- boolean, returns
trueif Sunblock is enabled
- boolean, returns
sunlight_correction_active- boolean, returns
trueif Sunblock is active, indicating that the Thermostat is located in direct sunlight
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
the following data values can be set with Thermostat read/write permissions:
fan_timer_active- boolean, returns
trueif 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
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).
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.
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.
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.