Structure

Nest structures represent physical structures in the real world. Typically a user's home, they serve as an organizing point for devices and will store data that applies to the whole home.

The Nest API provides access to the following structure-level data, dependent on the level of permissions granted:

• Structure name and device "where name" (location in the home)
• The list of devices in the home
• Energy event status (energy rush hour)
• Away state
• User ETA
• Security state
• Postal or zip code

Some structure-level features are covered in separate, more detailed API guides:

• Away & ETA—Away state, user ETA
• Energy—Energy event status
• Security—Security and deterrence

Structure permissions

For access to...	Select...
Most data values in the structures object	Away, ETA, Energy, or Postal code permissions
The name data value in the structures object	Structure read/write permission

See how permissions work in the interactive API Reference.

Structure identifiers

Name

The name of the structure defaults to "Home" but can be any string the user chooses. When you choose Structure read/write permission, you can change the structure name.

Wheres

wheres is an object set on a structure, containing where identifiers (where_id and name). Use wheres to create custom where names, or access standard where names.

Access to the wheres object requires Camera, Smoke+CO Alarm, or Thermostat permissions.

where_id

• A unique, Nest-generated identifier that represents name
• where_id is read-only, and is created automatically in the call to create a custom where name

name

• The display name of the device; can be any room name from a list we provide, or a custom name
• To create a custom where name, make a POST call to write a new, custom where name; the where_id is returned in the call
• Considerations
  • name cannot be edited or deleted after creation
  • name must be unique within the structure
  • If a device is paired to a structure, the custom where name associated with the device is accessible from the /structures/ path
  • To move a device with a custom where name to a different structure, unpair the device, and then re-pair the device with the desired name

Learn more about names for Nest Thermostats, Nest Protects and Nest Cams.

Other metadata

All data values are read only, unless otherwise specified.

Data Value	Description
structure_id	A string that uniquely represents this structure. Every developer will see a different ID for the same structure, but multiple products from the same developer will see the same ID
country_code	An ISO 3166-1 alpha-2 country code that maps to the registered location of the structure
postal_code	Postal or zip code, depending on the country
time_zone	An IANA time zone string that maps to the structure's time zone

Structure features

Smoke and CO alarm states

When you choose Smoke+CO read permission, you can access smoke_alarm_state and co_alarm_state in the structures object. These same data values are also available in the device object (devices/smoke_co_alarms).

See the Smoke+CO alarm guide for more information on these states.

Structure-related restrictions

Many data values work together to determine how devices behave in a structure.

• When a structure away state is set to away the word "ECO" is displayed on the Nest Thermostat, in the user's preferred language
• When a structure away state is set to away, you can:
  • set fan_timer_active
  • change target_temperature_f or target_temperature_c
• When a structure away state is set to home, you can:
  • make an ETA call (set trip id and arrival window)
• When Emergency Shutoff is active, you cannot set fan_timer_active
• When Emergency Heat is enabled, you cannot can set structure to away

Multiple structures

It's possible that a user has more than one structure attached to their Nest Account, so your product should offer a means for the user to choose from the available structures (a structure picker).

For example, when setting ETA, it is important that the user be able to choose a structure for the ETA destination. In a similar fashion, a user could have two smoke detectors in the "living room" of two different houses. If you need to do structure correlation with your own concept of a home, we recommend you do this during the authorization process.

Learn how users manage devices in multiple structures.

Device maximums

There are limits to how many devices Nest supports in a structure.

Device type	Max per structure
Nest Thermostat	20
Nest Cameras	10
Nest Protect	18

Error messages

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