Away & ETA

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.

How Home and Away works

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.

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

How ETA works

In some cases, users have a 3rd-party app that uses GPS to provide estimated time of arrival (ETA) data to the Nest API. In other cases, the user might use an app to manually enter their ETA. Or maybe the ETA is calcluated based on the user's regular schedule.

ETA apps that are integrated with the Nest Thermostat cause the thermostat to begin warming or cooling the home before the user arrives.

When the ETA/thermostat integration exists in the user's account, the ETA data is available for other Works with Nest developers to use in their Works with Nest integrations.

After the ETA is input into the Nest service, another Works with Nest integration can use it as a signal to prepare the home for the user's arrival.

1. The ETA is written by a Nest developer using the write-only PUT eta API call.
2. The Nest Thermostat uses this data.
3. If other developers want to use it, too, they can use the read-only GET eta_begin API call.

The important point to keep in mind is that ETA data must be input by a 3rd party. Nest does not currently provide ETA data. If the ETA data has not been written, the Nest API returns the default "1970-01-01T00:00:00.000Z" value.

Suppose, for example, that you are a lighting vendor. You can get the ETA data provided by the ETA/thermostat integration and use it as a signal to turn on the lights.

This way, not only is the temperature comfortable, the lights are also on when the user arrives home.

Reacting to changes in the ETA status opens up a wide range of opportunities for your products. For example, your products can:

• Turn on the TV as the user approaches home
• Open the garage door when the user is almost home
• Have music already playing when the user returns home

Away permissions

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

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:

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

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.

ETA is independent of home state. If the arrival time of an ETA conflicts with another ETA, the earliest arrival time takes precedence.

Make an ETA write call

ETA logic is dependent on the presence of a Thermostat in the structure. If no thermostat exists in the structure, calls made to the ETA object fail with the "No paired devices" error message. This error occurs even if other types of devices exist in the structure (for example, a Nest Cam or a Nest Protect).

Data values

An ETA call requires the following data values:

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 --location-trusted -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.