Notice: We're retiring Works with Nest. See the home page for more information.

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 Caution: This data value cannot be edited or deleted after creation.
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