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 |