Nest API 適用於所有 Nest Learning ThermostatTM 模型,但溫度控制器 E 搭配 Heat Link 除外。
使用者可以將多個 Nest Thermostat 新增至 devices/thermostats
群組,直到每個結構的上限為止。向這個資料位置發出呼叫時,即可存取 Nest Thermostat 資料 (同結構中裝置的資料值)。
下列所有值都位於 JSON 文件中的每個 devices/thermostats/device_id
下方。
裝置 ID
Nest Thermostat 專屬 ID。
說明 | |
---|---|
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 |
Software_version [軟體版本]
軟體版本。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/software_version |
|
退貨 | string 例如:「4.0」 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
結構 ID
建構專屬 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 |
名稱長
裝置的長顯示名稱。包含自訂 (標籤)、使用者建立或透過 wheres
建立。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/name_long |
|
退貨 | string 範例:「Hallway Thermostat (upsers)」 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
最後一次連線
最近一次與 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
冷氣系統 (有 AC)
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/can_cool |
|
退貨 | boolean 值:true、false |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
Can_heat
暖氣系統。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/can_heat |
|
退貨 | boolean 值:true、false |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
is_using_emergency_heat
冷熱泵在緊急氣值系統中用於冷卻。
緊急加熱功能開啟時:
- 使用者可以調整裝置的目標溫度,但必須等到緊急加熱功能關閉後才能變更模式
hvac_mode
仍可透過 API 變更
如要進一步瞭解 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 |
色溫
華氏或攝氏;與溫度顯示器搭配使用。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/temperature_scale |
|
退貨 | string enum 值:「F」、「C」 |
存取 | 讀取/寫入 |
服務遍及 | 讀取: 溫度控制器讀取 / v1-v6 溫度控制器讀取/寫入 / v1-v6 寫入: Thermostat 讀取/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 |
目標溫度
所需溫度,攝氏攝氏 0.5 度。用於 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
(at•• 冷模式)。
說明 | |
---|---|
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 度。使用於 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
(at•• 冷模式)。
說明 | |
---|---|
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 度。使用於 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 度。使用於 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 度。使用於 hvac_mode
= eco
時。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/eco_temperature_low_c |
|
退貨 | number 範例:19.5 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取/v6 溫度控制器/讀取/寫入/v6 |
out_temperature_high_f (已不適用)
最高溫度,以華氏度 (1°F) 顯示。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_high_f |
|
退貨 | number 範例:80 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
out_temperature_high_c (已不適用)
最大溫度以攝氏攝氏 0.5 度 (攝氏 0.5 度) 呈現。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_high_c |
|
退貨 | number 示例:24.5 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
out_temperature_low_f (已不適用)
最低溫度 (以整度華氏 1°F 度表示)。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_low_f |
|
退貨 | number 示例:65 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
out_temperature_low_c (已不適用)
最低溫度為攝氏攝氏 0.5 度,以攝氏度為單位。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/away_temperature_low_c |
|
退貨 | number 範例:19.5 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
hvac_mode
表示空調系統的暖氣/冷氣模式,例如熱 • 具備暖氣和冷氣溫度的系統,或是節能溫度節能。
- 如果溫度控制器已鎖定,則可變更
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 |
微候溫度
裝置測量的溫度,單位為華氏 (1°F)。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/ambient_temperature_f |
|
退貨 | number 示例:72 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
環境溫度
裝置測得的溫度,攝氏攝氏 0.5 度,單位為測量單位。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/ambient_temperature_c |
|
退貨 | number 範例:21.5 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v1-v6 溫度控制器已讀取/寫入 / v1-v6 |
度
裝置測量的濕度 (百分比 (%)) 格式,會四捨五入至最接近的 5% 百分比。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/humidity |
|
退貨 | number 示例:35 |
範圍 | 0-100 TB |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v2-v6 溫度控制器已讀取/寫入 / v2-v6 |
Hvac_state
指出空調系統是否正在暖氣、冷氣或關機。這個值應用於表示空調活動的狀態。
off
空調系統未主動啟動暖氣或冷氣, hvac_state
與風扇作業無關。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/hvac_state |
|
退貨 | string enum 值:「暖氣」、「烹飪」、「關閉」 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v3-v6 溫度控制器已讀取/寫入 / v3-v6 |
其中 ID
由 Nest 產生的專屬 ID,代表裝置的顯示名稱 name
。
進一步瞭解 Nest Thermostat、Nest Protect 和 Nest Cam 的名稱。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/where_id |
|
退貨 | string 例如:「d6reb_OZTM...」 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v4-v6 溫度控制器已讀取/寫入 / v4-v6 |
is_locked
溫度控制器鎖定狀態。設為 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 |
Lock_temp_min_f
最小的溫度控制器溫度 (以華氏度 (1°F) 為單位顯示)。當 is_locked
為 true
時。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_min_f |
|
退貨 | string 示例:65 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v5-v6 溫度控制器已讀取/寫入 / v5-v6 |
上鎖上限
「熱點鎖定」溫度上限 (以華氏 1°F 為單位)。當 is_locked
為 true
時。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_max_f |
|
退貨 | string 範例:80 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取 / v5-v6 溫度控制器已讀取/寫入 / v5-v6 |
上鎖時間
最小的熱度鎖定溫度 (以半度為 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 |
上鎖上限
「熱視圖鎖定」溫度上限 (以攝氏 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 -66 |
sunlight_更正_enabled
啟用封鎖功能的狀態。與 sunlight_correction_active
搭配使用。
true
會啟用 Sunblock 技術,並自動調節溫度控制器在陽光直射時讀取、設定正確溫度。
詳情請參閱什麼是解除封鎖功能?
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/sunlight_correction_enabled |
|
退貨 | boolean 值:true、false |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取/v6 溫度控制器/讀取/寫入/v6 |
sunlight_更正_active
「封鎖中」有效狀態。與 sunlight_correction_enabled
搭配使用。
如果使用 true
,則表示溫度控制器位於陽光直射處。
詳情請參閱什麼是解除封鎖功能?
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/sunlight_correction_active |
|
退貨 | boolean 值:true、false |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取/v6 溫度控制器/讀取/寫入/v6 |
其中_name
裝置的顯示名稱。與溫度控制器 where_id
建立關聯。可以是我們列出的清單中的任何會議室名稱,或是自訂名稱。進一步瞭解 Nest Thermostat、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 |
time_to_target [目標目標]
(即數分鐘) 導致結構達到目標溫度。
詳情請參閱時間溫度一節。
說明 | |
---|---|
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 會學習空調系統,並掌握達到目標溫度所需的時間。如果溫度控制器有足夠的資訊可預估達到目標溫度所需的時間,這個值就會從 training
變更為 ready
。
詳情請參閱時間溫度一節。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/time_to_target_training |
|
退貨 | string enum 值:「訓練」、「就緒」 |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取/v6 溫度控制器/讀取/寫入/v6 |
previous_hvac_mode
顯示上次選取的位置 hvac_mode
。從搭載舊版韌體的裝置使用 hvac_mode
= eco
時,才使用這項設定。
若想進一步瞭解如何切換貝塔生態和非電子模式,請參閱 Thermostat 指南。
說明 | |
---|---|
https://developer-api.nest.com/devices/thermostats/device_id/previous_hvac_mode |
|
退貨 | string 值:" Heat"、"cool"、"heat-cool", "off", blank (無值) |
存取 | 唯讀 |
服務遍及 | 溫度控制器讀取/v6 溫度控制器/讀取/寫入/v6 |