Away & ETA

Away

In the Nest API, the concept of "Home" or "Away" has a powerful effect on the behaviors of Nest's energy savings and convenience features. Reacting to changes in the Home/Away status opens up a wide range of opportunities for your products. For example, your products can:

  • Turn off the lights when the home goes into Away to conserve energy
  • Send a notification if the garage door is open when the home is Away
  • Play music when the house switches to Home

Nest uses a variety of signals to detect human presence in a Home. If Nest detects no presence for an extended period of time, it automatically sets the home to Away. When it detects human presence, it returns the structure to the Home state.

ETA (estimated time of arrival) can also be used as a signal to prepare the home for the user's arrival.

Away permissions

The following access permission levels are available for Away-related data values:



Access

Away read
Away read/write

ETA read

ETA read/write

Smoke+CO alarm read
Thermostat read
Thermostat read/write
away Yes Yes Yes
eta_begin (read only) Yes Yes
eta object (write only) Yes

For more info, see the Permissions Overview.

Away features

Home and Away

The away data value can tell you if Nest thinks the structure is occupied. The possible values are:

ValueDescription
homeThere is someone in the structure. This state can be set:
• by Nest if it has a high confidence from motion sensor data
• by the user via the Nest app, the Nest Thermostat, or your product
• algorithmically via ETA
awayThere is no one in the structure. The user has explicitly set the structure to away, either via the Nest app, the Nest Thermostat, or your product.
unknownIf no devices are associated with the structure, then the away state is unknown.

The Nest API provides the ability to directly set Home and Away, as well as listen for changes to these states. However, when setting Home and Away, it should be done as the Nest app does it: as the result of an explicit user request. Trying to algorithmically set this state runs the risk of creating a confusing user experience and is forbidden by the Nest design policies.

Be aware that users always have the ability to manually set the Home/Away state.

Learn more about how users set Home and Away states.

ETA

Away

ETA is an object with fields that can be set on a structure. It is used to let Nest know that a user is expected to return home at a specific time. When setting the ETA, a product generates a unique trip_id and provides an expected window of arrival, specified by the following values:

  • estimated_arrival_window_begin
  • estimated_arrival_window_end

Because circumstances around trips can change due to traffic, altered user plans, and other events, products should update ETA periodically as the trip progresses, providing Nest with a stream of estimated arrival times (5 minutes is an ideal interval).

The more information we receive, the more confident we can be in the reliability of ETA inputs, which makes us more confident when taking action to prepare the home.

Make an ETA call

An ETA call requires the following data values:

Name Type Description
trip_id string Unique ETA trip identifier
estimated_arrival_window_begin string Timestamp
Must be greater than NOW, in ISO 8601 format
estimated_arrival_window_end string Timestamp
Must be greater than estimated_arrival_window_begin, in ISO 8601 format

Because of the possibility of connection dropouts in GPS communications, we suggest a stream of samples, ideally once every 5 minutes.

Every ETA call must include a unique trip_id string that you define in the initial call. Other parameters can change with successive calls to the same trip_id.

An ETA call returns a 200 OK HTTP status code on success.

Examples

Curl
curl -L -X PUT -d \
  '{"trip_id":"sample-trip-id","estimated_arrival_window_begin":"2014-10-31T22:42:00.000Z","estimated_arrival_window_end":"2014-10-31T23:59:59.000Z"}' \
  "http://developer-api.nest.com/structures/5af48890-b516-11e3-9eff-123139166438/eta.json?auth=c.VG6bfzyOxAltaih6P4v..."

Cancel an ETA

To cancel an eta, send estimated_arrival_window_begin = 0. Check that you're sending an integer (0) in this call, not a string ("0"), or the call will fail.

Error messages

For information on what API call errors mean and how to handle them, see Error Messages.