Notice: We're retiring Works with Nest. See the home page for more information.

Google is committed to advancing racial equity for Black communities. See how.

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