Structure API

Users can add a maximum of three structures, with multiple devices per structure.

All the below values are found under each structures/structure_id in the JSON document.

structure_id

ID number of the structure. When you make a call to this data location, you can access the data values in this structure.

Details
https://developer-api.nest.com/structures/structure_id/structure_id
Returns	string Example: "VqFabWH21nw..."
Access	read-only
Available in	Thermostat read / v1-v6 Thermostat read/write / v1-v6 Smoke+CO read / v1-v5 Away read / v1-v2 Away read/write / v1-v2 ETA write / v1-v2 Postal code read / v2 Camera read / v1-v3 Camera read + images / v1-v4 Camera read/write / v1-v3 Camera read/write + images / v1-v4 Energy read / v2

thermostats

List of thermostats in the structure, by unique device identifier. This is an array of JSON objects that includes all thermostats in the structure.

Details
https://developer-api.nest.com/structures/structure_id/thermostats
Returns	array Example: [ "peyiJNo0IldT2YlIVtYaGQ",... ]
Access	read-only
Available in	Thermostat read / v1-v6 Thermostat read/write / v1-v6 Smoke+CO read / v1-v5 Away read / v1-v2 Away read/write / v1-v2 ETA write / v1-v2 Camera read / v2-v3 Camera read + images / v2-v4 Camera read/write / v2-v3 Camera read/write + images / v2-v4

smoke_co_alarms

List of smoke+CO alarms in the structure, by unique device identifier. This is an array of JSON objects that includes all smoke+CO alarms in the structure.

Details
https://developer-api.nest.com/structures/structure_id/smoke_co_alarms
Returns	array Example: [ "RTMTKxsQTCxzVcsySOHPxKoF4OyCifrs",... ]
Access	read-only
Available in	Thermostat read / v1-v6 Thermostat read/write / v1-v6 Smoke+CO read / v1-v5 Away read / v1-v2 Away read/write / v1-v2 ETA write / v1-v2 Camera read / v2-v3 Camera read + images / v2-v4 Camera read/write / v2-v3 Camera read/write + images / v2-v4

cameras

List of cameras in the structure, by unique device identifier. This is an array of JSON objects that includes all cameras in the structure.

Details
https://developer-api.nest.com/structures/structure_id/cameras
Returns	array Example: [ "awJo6rH...",... ]
Access	read-only
Available in	Thermostat read / v4-v6 Thermostat read/write / v4-v6 Smoke+CO read / v4-v5 Away read / v2 Away read/write / v2 ETA write / v2 Camera read / v1-v3 Camera read + images / v1-v4 Camera read/write / v1-v3 Camera read/write + images / v1-v4

away

Indicates the occupancy state of the structure.

Structures have two states related to presence: home or away. When no motion is sensed in the house, the structure will change from home to away.

Details
https://developer-api.nest.com/structures/structure_id/away
Returns	string Values: "home", "away"
Access	read/write
Available in	Read:   Thermostat read / v1-v6   Thermostat read/write / v1-v6   Smoke+CO read / v1-v5   Away read / v1-v2   Away read/write / v1-v2   ETA write / v1-v2 Write:   Away read/write / v1-v2

name

User-defined display name of the structure.

Details
https://developer-api.nest.com/structures/structure_id/name
Returns	string Examples: "My Home", "Beach House", "Mountain House"
Access	read/write
Available in	Read:   Thermostat read / v1-v6   Thermostat read/write / v1-v6   Smoke+CO read / v1-v5   Away read / v1-v2   Away read/write / v1-v2   ETA write / v1-v2   Postal code read / v2   Camera read / v1-v3   Camera read + images / v1-v4   Camera read/write / v1-v3   Camera read/write + images / v1-v4   Energy read / v2   Structure read/write / v1 Write:   Structure read/write / v1

country_code

Country code, in ISO 3166 alpha-2 format.

Details
https://developer-api.nest.com/structures/structure_id/country_code
Returns	string Examples: "US", "CA", "UK"
Access	read-only
Available in	Thermostat read / v1-v6 Thermostat read/write / v1-v6 Smoke+CO read / v1-v5 Away read / v1-v2 Away read/write / v1-v2 ETA write / v1-v2

postal_code

Postal or zip code, depending on the country.

Details
https://developer-api.nest.com/structures/structure_id/postal_code
Returns	string Examples: "94304", "94304-1027", "EC1A 1BB"
Access	read-only
Available in	Postal code read / v1-v2

peak_period_start_time

Start time of the energy rush hour event, in ISO 8601 format.

Details
https://developer-api.nest.com/structures/structure_id/peak_period_start_time
Returns	string Example: "2016-12-31T23:59:59.000Z"
Access	read-only
Available in	Thermostat read / v1-v6 Thermostat read/write / v1-v6 Energy read / v1-v2

peak_period_end_time

End time of the energy rush hour event, in ISO 8601 format.

Details
https://developer-api.nest.com/structures/structure_id/peak_period_end_time
Returns	string Example: "2016-12-31T23:59:59.000Z"
Access	read-only
Available in	Thermostat read / v1-v6 Thermostat read/write / v1-v6 Energy read / v1-v2

time_zone

Time zone at the structure, in IANA time zone format.

Details
https://developer-api.nest.com/structures/structure_id/time_zone
Returns	string Example: "America/Los_Angeles"
Access	read-only
Available in	Thermostat read / v1-v6 Thermostat read/write / v1-v6 Smoke+CO read / v1-v5 Away read / v1-v2 Away read/write / v2 ETA write / v1-v2

eta

ETA (estimated time of arrival) is an object 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. For information on how to make an ETA call, see the Away Guide.

Details
https://developer-api.nest.com/structures/structure_id/eta
Returns	object Example: "myTripID1024", "2014-10-31T22:42:00.000Z", "2016-12-31T23:59:59.000Z"
Parameters	trip_id A user-defined string identifying the trip estimated_arrival_window_begin A timestamp in ISO 8601 format. Must be greater than NOW. estimated_arrival_window_end A timestamp in ISO 8601 format. Must be greater than estimated_arrival_window_begin.
Access	write-only
Available in	ETA write / v1-v2

eta_begin

Timestamp of the earliest expected time of arrival in ISO 8601 format. Used to trigger actions or events.

Details
https://developer-api.nest.com/structures/structure_id/eta_begin
Returns	string Example: "2016-12-31T23:59:59.000Z"
Access	read-only
Available in	ETA read / v1

rhr_enrollment

Rush Hour Rewards enrollment status.

Details
https://developer-api.nest.com/structures/structure_id/rhr_enrollment
Returns	boolean Values: true, false
Access	read-only
Available in	Energy read / v1-v2

wwn_security_state

Structure security state.

Details
https://developer-api.nest.com/structures/structure_id/wwn_security_state
Type	string enum Values: "ok", "deter"
Access	read-only
Available in	Security state read / v1

wheres

An object containing where identifiers (where_id and name) for devices in the structure. name is the display name of the device. It can be any room name from a list we provide, or a custom name.

For more information on wheres, see the Structure Guide.

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

Details
https://developer-api.nest.com/structures/structure_id/wheres
Returns	object
Access	read-only
Available in	Read:   Thermostat read / v3-v6   Thermostat read/write / v3-v6   Smoke+CO read / v3-v5   Camera read / v1-v3   Camera read + images / v1-v4   Camera read/write / v1-v3   Camera read/write + images / v1-v4

where_id

A unique, Nest-generated identifier that represents name.

where_id is automatically created and returned during the call to create name.

Details
https://developer-api.nest.com/structures/structure_id/wheres/where_id/where_id
Returns	string Example: "Fqp6wJI..."
Access	read-only
Available in	Read: Thermostat read / v3-v6 Thermostat read/write / v3-v6 Smoke+CO read / v3-v5 Camera read / v1-v3 Camera read + images / v1-v4 Camera read/write / v1-v3 Camera read/write + images / v1-v4

name

The display name of the device.

Details
https://developer-api.nest.com/structures/structure_id/wheres/where_id/name
Returns	string Example: "Bedroom"
Access	read/write
Available in	Read:   Thermostat read / v3-v6   Thermostat read/write / v3-v6   Smoke+CO read / v3-v5   Camera read / v1-v3   Camera read + images / v1-v4   Camera read/write / v1-v3   Camera read/write + images / v1-v4

co_alarm_state

CO alarm status.

Details
https://developer-api.nest.com/structures/structure_id/co_alarm_state
Returns	string enum Values: "ok", "warning", "emergency"
Access	read-only
Available in	Smoke+CO read / v5

smoke_alarm_state

Smoke alarm status.

Details
https://developer-api.nest.com/structures/structure_id/smoke_alarm_state
Returns	string enum Values: "ok", "warning", "emergency"
Access	read-only
Available in	Smoke+CO read / v5