恆溫器API

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 = heatcool 時。

說明
https://developer-api.nest.com/devices/thermostats/device_id/target_temperature_f
退貨number
示例:72
範圍50-90
存取讀取/寫入
服務遍及溫度控制器讀取 / v1-v6
溫度控制器已讀取/寫入 / v1-v6

目標溫度

所需溫度,攝氏攝氏 0.5 度。用於 hvac_mode = heatcool 時。

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

表示空調系統的暖氣/冷氣模式,例如熱 • 具備暖氣和冷氣溫度的系統,或是節能溫度節能。

說明
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 ThermostatNest ProtectNest 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_flocked_temp_max_flocked_temp_min_clocked_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_lockedtrue 時。

說明
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_min_f
退貨string
示例:65
存取唯讀
服務遍及溫度控制器讀取 / v5-v6
溫度控制器已讀取/寫入 / v5-v6

上鎖上限

「熱點鎖定」溫度上限 (以華氏 1°F 為單位)。當 is_lockedtrue 時。

說明
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_max_f
退貨string
範例:80
存取唯讀
服務遍及溫度控制器讀取 / v5-v6
溫度控制器已讀取/寫入 / v5-v6

上鎖時間

最小的熱度鎖定溫度 (以半度為 0.5°C) 顯示的溫度。當 is_lockedtrue 時。

說明
https://developer-api.nest.com/devices/thermostats/device_id/locked_temp_min_c
退貨string
範例:19.5
存取唯讀
服務遍及溫度控制器讀取 / v5-v6
溫度控制器已讀取/寫入 / v5-v6

上鎖上限

「熱視圖鎖定」溫度上限 (以攝氏 0.5°C 度呈現的一半), 當 is_lockedtrue 時。

說明
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 ThermostatNest ProtectNest 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