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
Returnsstring
Example: "VqFabWH21nw..."
Accessread-only
Available inThermostat 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
Returnsarray
Example: [ "peyiJNo0IldT2YlIVtYaGQ",... ]
Accessread-only
Available inThermostat 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
Returnsarray
Example: [ "RTMTKxsQTCxzVcsySOHPxKoF4OyCifrs",... ]
Accessread-only
Available inThermostat 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
Returnsarray
Example: [ "awJo6rH...",... ]
Accessread-only
Available inThermostat 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
Returnsstring
Values: "home", "away"
Accessread/write
Available inRead:
  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
Returnsstring
Examples: "My Home", "Beach House", "Mountain House"
Accessread/write
Available inRead:
  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
Returnsstring
Examples: "US", "CA", "UK"
Accessread-only
Available inThermostat 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
Returnsstring
Examples: "94304", "94304-1027", "EC1A 1BB"
Accessread-only
Available inPostal 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
Returnsstring
Example: "2016-12-31T23:59:59.000Z"
Accessread-only
Available inThermostat 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
Returnsstring
Example: "2016-12-31T23:59:59.000Z"
Accessread-only
Available inThermostat 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
Returnsstring
Example: "America/Los_Angeles"
Accessread-only
Available inThermostat 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
Returnsobject
Example: "myTripID1024", "2014-10-31T22:42:00.000Z", "2016-12-31T23:59:59.000Z"
Parameters
trip_idA user-defined string identifying the trip
estimated_arrival_window_begin A timestamp in ISO 8601 format.
Must be greater than NOW.
estimated_arrival_window_endA timestamp in ISO 8601 format.
Must be greater than estimated_arrival_window_begin.
Accesswrite-only
Available inETA 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
Returnsstring
Example: "2016-12-31T23:59:59.000Z"
Accessread-only
Available inETA read / v1

rhr_enrollment

Rush Hour Rewards enrollment status.

Details
https://developer-api.nest.com/structures/structure_id/rhr_enrollment
Returnsboolean
Values: true, false
Accessread-only
Available inEnergy read / v1-v2

wwn_security_state

Structure security state.

Details
https://developer-api.nest.com/structures/structure_id/wwn_security_state
Typestring enum
Values: "ok", "deter"
Accessread-only
Available inSecurity 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
Returnsobject
Accessread-only
Available inRead:
  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
Returnsstring
Example: "Fqp6wJI..."
Accessread-only
Available inRead:
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
Returnsstring
Example: "Bedroom"
Accessread/write
Available inRead:
  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
Returnsstring enum
Values: "ok", "warning", "emergency"
Accessread-only
Available inSmoke+CO read / v5

smoke_alarm_state

Smoke alarm status.

Details
https://developer-api.nest.com/structures/structure_id/smoke_alarm_state
Returnsstring enum
Values: "ok", "warning", "emergency"
Accessread-only
Available inSmoke+CO read / v5