The Nest API works with all Nest Learning Thermostat™ models, except for the Thermostat E with Heat Link in the EU.
Users can add multiple Nest Thermostats to the devices/thermostats
group, up
to the maximum per
structure.
When you make a call to this data location, you can access Nest Thermostat data
(data values for devices in the structure).
All the below values are found under each
devices/thermostats/device_id
in the JSON document.
device_id
Nest Thermostat unique identifier.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/device_id |
|
Returns | string Example: "peyiJNo0IldT2YlIVtYaGQ" |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
locale
Specifies language and region (or country) preference.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/locale |
|
Returns | string Examples: "en-GB", "en-US", "es-US", "fr-CA", "fr-CA", "nl-NL" |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
software_version
Software version.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/software_version |
|
Returns | string Example: "4.0" |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
structure_id
Structure unique identifier.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/structure_id |
|
Returns | string Example: "VqFabWH21nw..." |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
name
Display name of the device. Can be any room name from a list we provide, or a custom name.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/name |
|
Returns | string Example: "Hallway" |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
name_long
Long display name of the device. Includes a custom (label), created by the user,
or via wheres
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/name_long |
|
Returns | string Example: "Hallway Thermostat (upstairs)" |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
last_connection
Timestamp of the last successful interaction with the Nest service, in ISO 8601 format.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/last_connection |
|
Returns | string Example: "2016-12-31T23:59:59.000Z" |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
is_online
Device connection status with the Nest service.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/is_online |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
can_cool
System ability to cool (has AC).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/can_cool |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
can_heat
System ability to heat.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/can_heat |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
is_using_emergency_heat
Emergency Heat status in systems with heat pumps for cooling.
When Emergency Heat is on:
- The user can adjust the target temperature on the device, but cannot change the mode until Emergency Heat is turned off
- The
hvac_mode
can still be changed via the API
See What's Emergency Heat? for more information on how the Nest Thermostat supports Emergency Heat.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/is_using_emergency_heat |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
has_fan
System ability to control the fan independently from heating or cooling.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/has_fan |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
fan_timer_active
Indicates if the fan timer is engaged; used with
fan_timer_duration
to turn on the
fan for a (user-specified) preset duration.
See Advanced Fan Control for more information on how customers set fan duration.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/fan_timer_active |
|
Returns | boolean Values: true, false |
Access | read/write |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
fan_timer_timeout
Timestamp showing when the fan timer reaches 0 (stop time), in ISO 8601 format.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/fan_timer_timeout |
|
Returns | string Example: "2016-12-31T23:59:59.000Z" |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
has_leaf
Displayed when the thermostat is set to an energy-saving temperature.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/has_leaf |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
temperature_scale
Fahrenheit or Celsius; used with temperature display.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/temperature_scale |
|
Returns | string enum Values: "F", "C" |
Access | read/write |
Available in | Read: Thermostat read / v1-v6 Thermostat read/write / v1-v6 Write: Thermostat read/write / v5-v6 |
target_temperature_f
Desired temperature, in full degrees Fahrenheit (1°F). Used when
hvac_mode
= heat
or cool
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_f |
|
Returns | number Example: 72 |
Range | 50-90 |
Access | read/write |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
target_temperature_c
Desired temperature, in half degrees Celsius (0.5°C). Used when
hvac_mode
= heat
or cool
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_c |
|
Returns | number Example: 21.5 |
Range | 9-32 |
Access | read/write |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
target_temperature_high_f
Maximum target temperature, displayed in whole degrees Fahrenheit (1°F).
Used when hvac_mode
= heat-cool
(Heat•Cool mode).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_high_f |
|
Returns | number Example: 80 |
Access | read/write |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
target_temperature_high_c
Maximum target temperature, displayed in half degrees Celsius (0.5°C). Used
when hvac_mode
= heat-cool
(Heat•Cool
mode).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_high_c |
|
Returns | number Example: 24.5 |
Access | read/write |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
target_temperature_low_f
Minimum target temperature, displayed in whole degrees Fahrenheit (1°F).
Used when hvac_mode
= heat-cool
(Heat•Cool mode).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_low_f |
|
Returns | number Example: 65 |
Access | read/write |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
target_temperature_low_c
Minimum target temperature, displayed in half degrees Celsius (0.5°C). Used
when hvac_mode
= heat-cool
(Heat•Cool
mode).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_low_c |
|
Returns | number Example: 19.5 |
Access | read/write |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
eco_temperature_high_f
Maximum Eco Temperature, displayed in whole degrees Fahrenheit (1°F). Used
when hvac_mode
= eco
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_high_f |
|
Returns | number Example: 80 |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
eco_temperature_high_c
Maximum Eco Temperature, displayed in half degrees Celsius (0.5°C). Used
when hvac_mode
= eco
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_high_c |
|
Returns | number Example: 24.5 |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
eco_temperature_low_f
Minimum Eco Temperature, displayed in whole degrees Fahrenheit (1°F). Used
when hvac_mode
= eco
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_low_f |
|
Returns | number Example: 65 |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
eco_temperature_low_c
Minimum Eco Temperature, displayed in half degrees Celsius (0.5°C). Used
when hvac_mode
= eco
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_low_c |
|
Returns | number Example: 19.5 |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
away_temperature_high_f (DEPRECATED)
Maximum away temperature, displayed in whole degrees Fahrenheit (1°F).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_high_f |
|
Returns | number Example: 80 |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
away_temperature_high_c (DEPRECATED)
Maximum away temperature, displayed in half degrees Celsius (0.5°C).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_high_c |
|
Returns | number Example: 24.5 |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
away_temperature_low_f (DEPRECATED)
Minimum away temperature, displayed in whole degrees Fahrenheit (1°F).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_low_f |
|
Returns | number Example: 65 |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
away_temperature_low_c (DEPRECATED)
Minimum away temperature, displayed in half degrees Celsius (0.5°C).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_low_c |
|
Returns | number Example: 19.5 |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
hvac_mode
Indicates HVAC system heating/cooling modes, like Heat•Cool for systems with heating and cooling capacity, or Eco Temperatures for energy savings.
hvac_mode
can be changed if the Thermostat is lockedtarget_temperature_f
andtarget_temperature_c
cannot be changed ifhvac_mode
=off
oreco
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/hvac_mode |
|
Returns | string enum Values: "heat", "cool", "heat-cool", "eco", "off" |
Access | read/write |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
ambient_temperature_f
Temperature, measured at the device, in whole degrees Fahrenheit (1°F).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/ambient_temperature_f |
|
Returns | number Example: 72 |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
ambient_temperature_c
Temperature, measured at the device, in half degrees Celsius (0.5°C).
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/ambient_temperature_c |
|
Returns | number Example: 21.5 |
Access | read-only |
Available in | Thermostat read / v1-v6 Thermostat read/write / v1-v6 |
humidity
Humidity, in percent (%) format, measured at the device, rounded to the nearest 5%.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/humidity |
|
Returns | number Example: 35 |
Range | 0-100 |
Access | read-only |
Available in | Thermostat read / v2-v6 Thermostat read/write / v2-v6 |
hvac_state
Indicates whether HVAC system is actively heating, cooling or is off. Use this value to indicate HVAC activity state.
When off
, the HVAC system is not actively heating or cooling. hvac_state
is
independent of fan operation.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/hvac_state |
|
Returns | string enum Values: "heating", "cooling", "off" |
Access | read-only |
Available in | Thermostat read / v3-v6 Thermostat read/write / v3-v6 |
where_id
A unique, Nest-generated identifier that represents
name
, the display name of the device.
Learn more about where names for Nest Thermostats, Nest Protects and Nest Cams.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/where_id |
|
Returns | string Example: "d6reb_OZTM..." |
Access | read-only |
Available in | Thermostat read / v4-v6 Thermostat read/write / v4-v6 |
is_locked
Thermostat Lock status. When true, the Thermostat
Lock
feature is enabled, and restricts the temperature range to these min/max values:
locked_temp_min_f
,
locked_temp_max_f
,
locked_temp_min_c
, and
locked_temp_max_c
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/is_locked |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v5-v6 Thermostat read/write / v5-v6 |
locked_temp_min_f
Minimum Thermostat
Lock
temperature, displayed in whole degrees Fahrenheit (1°F). Used when
is_locked
is true
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_min_f |
|
Returns | string Example: 65 |
Access | read-only |
Available in | Thermostat read / v5-v6 Thermostat read/write / v5-v6 |
locked_temp_max_f
Maximum Thermostat
Lock
temperature, displayed in whole degrees Fahrenheit (1°F). Used when
is_locked
is true
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_max_f |
|
Returns | string Example: 80 |
Access | read-only |
Available in | Thermostat read / v5-v6 Thermostat read/write / v5-v6 |
locked_temp_min_c
Minimum Thermostat
Lock
temperature, displayed in displayed in half degrees Celsius (0.5°C). Used
when is_locked
is true
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_min_c |
|
Returns | string Example: 19.5 |
Access | read-only |
Available in | Thermostat read / v5-v6 Thermostat read/write / v5-v6 |
locked_temp_max_c
Maximum Thermostat
Lock
temperature, displayed in displayed in half degrees Celsius (0.5°C). Used
when is_locked
is true
.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_max_c |
|
Returns | string Example: 24.5 |
Access | read-only |
Available in | Thermostat read / v5-v6 Thermostat read/write / v5-v6 |
label
Thermostat custom label. Appears in parentheses, after the where name.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/label |
|
Returns | string Examples: "Upstairs", "Guest room", "Playroom" |
Access | read/write |
Available in | Read: Thermostat read / v6 Thermostat read/write / v6 Write: Thermostat read/write / v5-v6 |
sunlight_correction_enabled
Sunblock enabled status. Used with
sunlight_correction_active
.
When true
, Sunblock technology is enabled, and the Thermostat is automatically
adjusting to direct sunlight, reading and setting the correct temperature.
For more info, see What is Sunblock?
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/sunlight_correction_enabled |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
sunlight_correction_active
Sunblock active status. Used with
sunlight_correction_enabled
.
When true
, indicates that the Thermostat is located in direct sunlight.
For more info, see What is Sunblock?
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/sunlight_correction_active |
|
Returns | boolean Values: true, false |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
where_name
The display name of the device. Associated with the Thermostat
where_id
. Can be any room name from a list
we provide, or a custom name. Learn more about where names for Nest Thermostats, Nest Protects and Nest Cams.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/where_name |
|
Returns | string Example: "Hallway" |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
fan_timer_duration
Specifies the length of time (in minutes) that the fan is set to run.
The fan_timer_active
setting turns
on the fan. The fan_timer_timeout
value indicates the timestamp when fan_timer_duration
is set to
end.
To learn how customers set the fan timer, see Timer Duration.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/fan_timer_duration |
|
Returns | int Values: 15, 30, 45, 60, 120, 240, 480, 720 |
Access | read/write |
Available in | Read: Thermostat read / v6 Thermostat read/write / v6 Write: Thermostat read/write / v6 |
time_to_target
The time, in minutes, that it will take for the structure to reach the target temperature.
See Time-to-Temperature for more information.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/time_to_target |
|
Returns | string enum Values: "~0", "<5", "~15", "~90", "120" |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
time_to_target_training
When in training mode, the Nest Thermostat learns about the HVAC system and
discovers how much time it takes to reach the target temperature. When the
Thermostat has enough information to make a reasonable estimate of the time to
reach the target temperature, this value will change from training
to ready
.
See Time-to-Temperature for more information.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/time_to_target_training |
|
Returns | string enum Values: "training", "ready" |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |
previous_hvac_mode
Displays the last-selected hvac_mode
. Used
when switching from hvac_mode
= eco
on a device with outdated firmware.
To learn more about switching between Eco and non-Eco modes, see the Thermostat Guide.
Details | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/previous_hvac_mode |
|
Returns | string Values: "heat", "cool", "heat-cool", "off", blank (no value) |
Access | read-only |
Available in | Thermostat read / v6 Thermostat read/write / v6 |