Your product can use the Nest API to help prevent home intrusions.
When all family members are away from home, the structure enters away
mode.
When a Nest Cam detects a person, the Camera API's /last_event/has_person
field changes to true
.
These two states work together to trigger the Works with Nest Security API, as follows:
If a Nest Cam detects the presence of a person while the structure is in away
mode, the structure enters deter
mode.
When your product detects that the structure is in deter
mode, your product
can make the home "pretend" to be occupied by altering the home environment in
some way, such as turning on the lights, playing music, or opening blinds to
make an intruder more visible.
In this way, the home becomes a less inviting target for attack.
Requirements
To use the Security API:
- Your client must have these permissions:
- Security state read / v1
- Structure read/write / v1
- Camera read / v3
- The structure
away
state must be accurate, meaning:- All home occupants must be added as family members in the Nest app.
- All family members must have the Nest app installed on their phone with Home/Away Assist enabled.
- The structure must have at least one Nest Cam capable of sending person alerts. For some Nest Cam models, the Nest Cam must have a Nest Aware subscription to get person alerts.
Learn more about the alerts users get from different Camera models.
Security features
The security state escalates to deter
when the following criteria are met:
- Structure state is
away
. - Structure contains at least one Nest Cam that:
- is online and actively streaming
- triggers a last event where
has_person = "true"
A deter
state is re-evaluated after several minutes and relaxed to ok
if no
further has_person
events have occurred.
The security state automatically switches to ok
when the structure state is
Home
.
A Works with Nest product that reacts to a deter
state should also react to the
de-escalation of that state. For example, lights and music that turn on to
simulate occupancy in a deter
state, should eventually turn off after the
www_security_state
de-escalates to ok
.
Security permissions
To use the security API, choose the Security state read / v1 permission.
There are no write permissions available for the security API.
Security values
Use the wwn_security_state
field to view the security state.
Value | Description |
---|---|
ok |
Normal operation, all is well in the structure |
deter |
Person detected while the structure state is away |