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

此页面由 Cloud Translation API 翻译。

恒温器API

Nest API 适用于所有 Nest Learning ThermostatTM 型号，欧盟的 Heat Link 除外。

用户可以向 devices/thermostats 组添加多个 Nest Thermostat，最多可达到每个结构的数量上限。当您调用此数据位置时，可以访问 Nest Thermostat 数据（结构中设备的数据值）。

您可以在 JSON 文档中的每个 devices/thermostats/device_id 下找到以下所有值。

device_id [设备 ID]

Nest Thermostat 唯一标识符。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/device_id`
返回结果	`string` 示例：“peyiJNo0IldT2YlIVtYaGQ”
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

语言区域

指定语言和区域（或国家/地区）偏好设置。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/locale`
返回结果	`string` 示例：“en-GB”、“en-US”、“es-US”、“fr-CA”、“fr-CA”、“nl-NL”
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

软件版本

软件版本。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/software_version`
返回结果	`string` 示例：“4.0”
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

structure_id

结构唯一标识符。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/structure_id`
返回结果	`string` 示例：“VqFabWH21nw...”
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

名称

设备的显示名。可以是我们提供的列表中的任意房间名称，也可以是自定义名称。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/name`
返回结果	`string` 示例：“走廊”
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

name_long

设备的长显示名。包括由用户创建的或通过wheres创建的自定义（标签）。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/name_long`
返回结果	`string` 示例：“Hallway Thermostat (upstairs)”
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

last_connection

与 Nest 服务上次成功互动的时间戳（采用 ISO 8601 格式）。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/last_connection`
返回结果	`string` 示例：“2016-12-31T23:59:59.000Z”
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

is_online

Nest 服务的设备连接状态。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/is_online`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

can_cool

系统制冷能力（带空调）。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/can_cool`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

can 子

供暖系统。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/can_heat`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

is_using_emergency_heat

配备用于进行冷却的热的系统的应急热源状态。

应急热源开启时：

用户可以调整设备上的目标温度，但必须关闭应急热源，才能更改模式
您仍可通过 API 更改 hvac_mode

如需详细了解 Nest Thermostat 如何支持应急热源，请参阅什么是紧急热源？。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/is_using_emergency_heat`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

has_fan

独立于供暖或制冷系统控制风扇的系统。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/has_fan`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

fan_timer_active

指示风扇计时器是否处于启用状态；与 fan_timer_duration 搭配使用，可将风扇开启（用户指定）预设时长。

如需详细了解客户如何设置风扇时长，请参阅高级风扇控制。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/fan_timer_active`
返回结果	`boolean` 值：true、false
访问权限	读写
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

fan_timer_timeout

风扇计时器达到 0（停止时间）时显示的时间戳（采用 ISO 8601 格式）。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/fan_timer_timeout`
返回结果	`string` 示例：“2016-12-31T23:59:59.000Z”
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

has_leaf

在恒温器已设为节能温度时显示。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/has_leaf`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

temperature_scale

华氏度或摄氏度；用于温度显示。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/temperature_scale`
返回结果	`string enum` 值：“F”或“C”
访问权限	读写
支持的语言	读取：温控器读取 / v1-v6 温控器读取/写入 / v1-v6 写入：温控器读取/write / v5-v6

target_temperature_f

所需的温度，以全华氏度 (1°F) 为单位。当 hvac_mode = heat 或 cool 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_f`
返回结果	`number` 示例：72
范围	50-90
访问权限	读写
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

target_temperature_c

所需的温度，以 0.5°C (0.5°C) 为单位。当 hvac_mode = heat 或 cool 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_c`
返回结果	`number` 示例：21.5
范围	9-32
访问权限	读写
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

target_temperature_high_f

最高目标温度，以整华氏度 (1°F) 显示。当 hvac_mode = heat-cool（适温模式）时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_high_f`
返回结果	`number` 示例：80
访问权限	读写
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

target_temperature_high_c

最高目标温度，以 0.5°C (0.5°C) 为单位显示。当 hvac_mode = heat-cool（适温模式）时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_high_c`
返回结果	`number` 示例：24.5
访问权限	读写
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

target_temperature_low_f

最低目标温度，以华氏度 (1°F) 为单位显示。当 hvac_mode = heat-cool（适温模式）时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_low_f`
返回结果	`number` 示例：65
访问权限	读写
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

target_temperature_low_c

最低目标温度，以半摄氏度 (0.5°C) 显示。当 hvac_mode = heat-cool（适温模式）时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_low_c`
返回结果	`number` 示例：19.5
访问权限	读写
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

eco_temperature_high_f

最高温度，以整华氏度 (1°F) 显示。在 hvac_mode = eco 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_high_f`
返回结果	`number` 示例：80
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

eco_temperature_high_c

最高节能温度，以半摄氏度 (0.5°C) 显示。在 hvac_mode = eco 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_high_c`
返回结果	`number` 示例：24.5
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

eco_temperature_low_f [节能温度]

最低节能温度，以整华氏度 (1°F) 显示。在 hvac_mode = eco 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_low_f`
返回结果	`number` 示例：65
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

eco_temperature_low_c

最低节能温度，以半摄氏度 (0.5°C) 显示。在 hvac_mode = eco 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_low_c`
返回结果	`number` 示例：19.5
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

离开_温度_高_f（已弃用）

最高出发温度，以全华氏度 (1°F) 为单位显示。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_high_f`
返回结果	`number` 示例：80
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

客厅温度_高_c（已弃用）

最高离开温度，以半摄氏度 (0.5°C) 显示。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_high_c`
返回结果	`number` 示例：24.5
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

离开_温度_低_f（已弃用）

最低出发温度，以全华氏度 (1°F) 为单位显示。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_low_f`
返回结果	`number` 示例：65
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

客厅温度_低_c（已弃用）

最低出发温度，以半摄氏度 (0.5°C) 显示。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_low_c`
返回结果	`number` 示例：19.5
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

hvac_mode

用于指示 HVAC 系统的供暖/制冷模式，例如“供暖”/“制冷”模式（用于供暖和制冷）或“节能”温度（用于节省能源）。

如果温控器已锁定，则可以更改 hvac_mode
如果 hvac_mode = off 或 eco，则无法更改 target_temperature_f 和 target_temperature_c

详情
`https://developer-api.nest.com/devices/thermostats/device_id/hvac_mode`
返回结果	`string enum` 值：“heat”、“cool”、“heat-cool”、“eco”、“off”
访问权限	读写
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

ambient_temperature_f（环境温度）

设备温度，以全华氏度 (1°F) 为单位。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/ambient_temperature_f`
返回结果	`number` 示例：72
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

ambient_temperature_c（环境温度）

设备温度，以半摄氏度 (0.5°C) 为单位。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/ambient_temperature_c`
返回结果	`number` 示例：21.5
访问权限	只读
支持的语言	温控器读取 / v1-v6 温控器读取/写入 / v1-v6

humidity

设备湿度以百分比 (%) 格式测量，四舍五入为最接近的 5%。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/humidity`
返回结果	`number` 示例：35
范围	0-100
访问权限	只读
支持的语言	温控器读取 / v2-v6 温控器读取/写入 / v2-v6

hvac_state

指示 HVAC 系统是正在供暖、制冷还是关闭。请使用该值指示 HVAC 活动状态。

off 时，HVAC 系统未启动供暖或制冷。hvac_state 与风扇操作无关。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/hvac_state`
返回结果	`string enum` 值：“供暖”、“制冷”、“关闭”
访问权限	只读
支持的语言	温控器读取 / v3-v6 温控器读取/写入 / v3-v6

地点 ID

由 Nest 生成的唯一标识符，表示 name（设备的显示名）。

详细了解 Nest 温控器、Nest Protect 和 Nest Cam 的名称。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/where_id`
返回结果	`string` 示例：“d6reb_OZTM...”
访问权限	只读
支持的语言	温控器读取 / v4-v6 温控器读取/写入 / v4-v6

已锁定

恒温器锁定状态。如果为 true，则启用温控器锁定功能，并将温度范围限制为以下最小值/最大值：locked_temp_min_f。 locked_temp_max_f、locked_temp_min_c 和 locked_temp_max_c。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/is_locked`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v5-v6 温控器读取/写入 / v5-v6

已锁定的临时温度

Thermostat Lock 的最低温度，以整华氏度 (1°F) 显示。当 is_locked 为 true 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_min_f`
返回结果	`string` 示例：65
访问权限	只读
支持的语言	温控器读取 / v5-v6 温控器读取/写入 / v5-v6

lock_temp_max_f

恒温器锁定的最高温度，以整华氏度 (1°F) 显示。当 is_locked 为 true 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_max_f`
返回结果	`string` 示例：80
访问权限	只读
支持的语言	温控器读取 / v5-v6 温控器读取/写入 / v5-v6

已锁定的临时温度

Thermostat Lock 的最低温度，以半摄氏度 (0.5°C) 显示。在 is_locked 为 true 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_min_c`
返回结果	`string` 示例：19.5
访问权限	只读
支持的语言	温控器读取 / v5-v6 温控器读取/写入 / v5-v6

lock_temp_max_c

Thermostat Lock 最高温度，以半摄氏度 (0.5°C) 显示。在 is_locked 为 true 时使用。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_max_c`
返回结果	`string` 示例：24.5
访问权限	只读
支持的语言	温控器读取 / v5-v6 温控器读取/写入 / v5-v6

详情
`https://developer-api.nest.com/devices/thermostats/device_id/label`
返回结果	`string` 示例：“楼上”、“客房”、“游戏室”
访问权限	读写
支持的语言	读取：温控器读取 / v6 温控器读取/写入 / v6 写入：温控器读取/写入 / v5 -6

sunlight_correct_enabled

Sunblock 启用状态。与 sunlight_correction_active 搭配使用。启用 true 后，系统便会启用 Sunblock 技术，并且恒温器会自动根据日光，调整和设置正确的温度。

如需了解详情，请参阅什么是 Sunblock？

详情
`https://developer-api.nest.com/devices/thermostats/device_id/sunlight_correction_enabled`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

日光修正

停用活动状态。与 sunlight_correction_enabled 搭配使用。为 true 时，表示恒温器位于阳光直射处。

如需了解详情，请参阅什么是 Sunblock？

详情
`https://developer-api.nest.com/devices/thermostats/device_id/sunlight_correction_active`
返回结果	`boolean` 值：true、false
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

其中 name_name

设备的显示名。与恒温器 where_id 相关联。它可以是我们提供的列表中的任何房间名称，也可以是自定义名称。详细了解 Nest 温控器、Nest Protect 和 Nest Cam 的名称。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/where_name`
返回结果	`string` 示例：“走廊”
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

fan_timer_duration

指定风扇运行的时长（以分钟为单位）。

fan_timer_active 设置会开启风扇。fan_timer_timeout 值表示将 fan_timer_duration 设置为结束时的时间戳。

如需了解客户如何设置风扇计时器，请参阅计时器时长。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/fan_timer_duration`
返回结果	`int` 值：15、30、45、60、120、240、480、720
访问权限	读写
支持的语言	读取：温控器读取 / v6 温控器读取/写入 / v6 写入：温控器读取/写入 / v6

目标时间

结构达到目标温度所需的时间（以分钟为单位）。

如需了解详情，请参阅控温时间。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/time_to_target`
返回结果	`string enum` 值：“~0”、“<5”、“~15”、“~90”、“120”
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

time_to_target_training [目标训练时间]

当设备处于训练模式时，Nest Thermostat 会学习 HVAC 系统，并了解达到目标温度所需的时间。当恒温器具有足够的信息来合理估算达到目标温度的时间时，此值会从 training 更改为 ready。

如需了解详情，请参阅控温时间。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/time_to_target_training`
返回结果	`string enum` 值：“training”、“ready”
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6

previous_hvac_mode

显示上次选择的 hvac_mode。在具有过时固件的设备上从 hvac_mode = eco 切换时使用。

如需详细了解如何在节能模式和非节能模式之间切换，请参阅温控器指南。

详情
`https://developer-api.nest.com/devices/thermostats/device_id/previous_hvac_mode`
返回结果	`string` 值：“heat”、“cool”、“heat-cool”、“off”、“blank”（无值）
访问权限	只读
支持的语言	温控器读取 / v6 温控器读取/写入 / v6