Nest Protect is designed to detect smoke and carbon monoxide (CO) in a residential environment, with multiple sensors to help it understand what's happening in the home.
The Nest API provides access to the following data on Nest Protect:
- Smoke or carbon monoxide (CO) alarm status
- Battery health state
- Last manual test status and timestamp
- Online status and last connection information
- Structure name and device "where name" (location in the home)
Smoke+CO permissions
For read access to all Smoke+CO alarm API data values, select the Smoke+CO read permission for your client.
There are no write permissions available for the Smoke+CO alarm API.
Smoke+CO identifiers
Device
Nest devices are listed by type as an array of IDs, which can be used to
uniquely identify a device via the device path. So a smoke+co alarm ID of
"RTMTKxs..." means that you can load the smoke+co alarm device model at
devices/smoke_co_alarms/RTMTKxs... via the API.
When a device is connected to multiple products, each developer will see a different ID for that device. For a device that has installed multiple products from the same developer, the developer will see the same ID.
Name
Two name attributes are provided. The shorter name attribute is displayed in
user interface labels, while name_long is used in long form text.
name
In this example, name is "Nest Protect".
name_long
In this example, name_long is "Basement Nest Protect".
Where
where_id
- A unique, Nest-generated identifier that represents
name where_idis read-only, and is created automatically in the call to create a custom wherename
Learn more about where names for Nest Thermostats, Nest Protects and Nest Cams.
where_name
When you choose the Smoke+CO read
permission, you can
access the device where_name from the device object
(devices/smoke_co_alarms).
Other metadata
All data values are read only, unless otherwise specified.
| Data Value | Description |
|---|---|
locale |
The language and country code assigned to this device |
software_version
|
A string that represents the firmware currently installed on the device |
structure_id
|
A string that uniquely represents this structure; this is the structure that the device is paired with |
last_connection
|
The timestamp of the last successful connection to the Nest service |
is_online
|
Online status. This is determined by Nest using the
last_connection time and an expected reconnection
window that is device-specific. |
Smoke+CO features
Battery health
Use the
battery_health
field to view the battery health state.
| Value | Description |
|---|---|
ok |
Battery level ok |
replace |
Battery level low, should be replaced |
CO alarm
Use the
co_alarm_state
field to view the CO alarm state.
| Value | Description |
|---|---|
ok |
Normal operation |
warning |
Detection of rising CO levels |
emergency |
CO levels too high, user should exit the home |
Smoke alarm
Use the
smoke_alarm_state
field to view the smoke alarm state.
| Value | Description |
|---|---|
ok |
Normal operation |
warning |
Detection of rising smoke levels |
emergency |
Smoke levels too high, user should exit the home |
Manual test
Use these fields to check if a manual smoke or CO test is currently active, and the last time a successful smoke or CO test was performed.
is_manual_test_active—returnstrueif a smoke or test is activelast_manual_test_time
UI color state
To make it easier to design a coherent cross-product UI, we've provided the
ui_color_state
field, which gives a high-level indication of the overall state of the Nest
Protect. It is derived from is_online, battery_health, co_alarm_state, and
smoke_alarm_state, providing an aggregate condition that reflects the actual
color indicators displayed in the Nest app.
Error messages
For information on what API call errors mean and how to handle them, see Error Messages.