Thermostat API

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 locked
• target_temperature_f and target_temperature_c cannot be changed if hvac_mode = off or eco

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 betwen 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