
Las estructuras de Nest representan estructuras físicas en el mundo real. Por lo general, la casa de un usuario sirve como punto de organización para los dispositivos y almacena datos que se aplican a toda la casa.
La API de Nest proporciona acceso a los siguientes datos a nivel de la estructura, según el nivel de permisos otorgados:
- Nombre de la estructura y el dispositivo "where name" (ubicación de la casa)
- La lista de dispositivos del hogar
- Estado del evento de energía (hora pico de energía)
- Estado Ausente
- ETA del usuario
- Estado de seguridad
- Código postal
Algunas funciones a nivel de estructura se tratan en guías de API independientes y más detalladas:
- Ausente y ETA: estado Ausente y ETA
- Energía: estado de eventos de energía
- Seguridad: Disuasión y seguridad
Permisos de estructura
Para acceder a... | Selecciona… |
---|---|
La mayoría de los valores de datos del objeto structures |
Permisos Ausente, ETA, Energía o Código postal |
El valor de datos name en el objeto structures |
Permiso de estructura de lectura y escritura |
Consulta el funcionamiento de los permisos en la referencia interactiva de la API.
Identificadores de la estructura
Nombre
El nombre predeterminado de la estructura es "Home", pero puede ser cualquier string que elija el usuario. Cuando eliges el permiso Estructura de lectura y escritura, puedes cambiar la estructura name
.
Dónde
wheres
es un objeto establecido en una estructura, que contiene los identificadores de ubicación (where_id
y name
). Usa wheres
para crear nombres personalizados de nombres o accede a esos nombres estándar.
El acceso al objeto wheres
requiere permisos de Cámara, Alarma de humo + CO o Termostato.
where_id
- Un identificador único generado por Nest que representa a
name
where_id
es de solo lectura y se crea de forma automática en la llamada para crear una instancia personalizada.name
name
- El nombre visible del dispositivo; puede ser cualquier nombre de habitación de la lista que proporcionamos, o un nombre personalizado
- Para crear un personalizado en el que
name
, realiza una llamada POST a fin de escribir uno nuevo, en el quename
se muestrawhere_id
en la llamada - Consideraciones
- No se puede editar ni borrar
name
después de crearlo name
debe ser único en la estructura- Si un dispositivo está vinculado a una estructura, el personalizado en el que se puede acceder al
name
asociado con el dispositivo desde la ruta de acceso/structures/
- Para mover un dispositivo con una ubicación personalizada en el que
name
a una estructura diferente, desvincula el dispositivo y, luego, vuelve a sincronizar el dispositivo con el nombre que quieras.
- No se puede editar ni borrar
Obtén más información sobre los nombres de los termostatos Nest, los Nest Protects y las Nest Cams.
Otros metadatos
Todos los valores de datos son de solo lectura, a menos que se especifique lo contrario.
Valor de los datos | Descripción |
---|---|
structure_id
|
Es una string que representa de forma única esta estructura. Cada desarrollador verá un ID diferente para la misma estructura, pero varios productos del mismo desarrollador verán el mismo ID. |
country_code
|
Un código de país ISO 3166-1 alpha-2 que se asigna a la ubicación registrada de la estructura |
postal_code
|
Código postal, según el país |
time_zone
|
Una string de zona horaria de IANA que se asigna a la zona horaria de la estructura |
Características de la estructura
Estados de la alarma de humo y monóxido de carbono
Cuando eliges Permiso de lectura de humo y monóxido de carbono, puedes acceder a smoke_alarm_state
y co_alarm_state
en el objeto structures
.
Estos mismos valores de datos también están disponibles en el objeto del dispositivo (devices/smoke_co_alarms
).
Consulta la guía de la alarma de humo/monóxido de carbono para obtener más información sobre estos estados.
Restricciones relacionadas con la estructura
Muchos valores de datos trabajan juntos para determinar el comportamiento de los dispositivos en una estructura.
- Cuando se establece un estado
away
de estructura enaway
, se muestra la palabra "ECO" en el Nest Thermostat, en el idioma preferido del usuario. - Cuando un estado de estructura
away
se establece enaway
, puedes hacer lo siguiente:- establecer
fan_timer_active
- cambiar
target_temperature_f
otarget_temperature_c
- establecer
- Cuando un estado de estructura
away
se establece enhome
, puedes hacer lo siguiente:- hacer una llamada de ETA (establecer ID de viaje y período de llegada)
- Cuando el Corte de emergencia está activo, no puedes establecer
fan_timer_active
. - Cuando está habilitada la opción Calefactor de emergencia, no puedes establecer la estructura en
away
Varias estructuras
Es posible que un usuario tenga más de una estructura adjunta a su cuenta de Nest, por lo que tu producto debe ofrecer un medio para que el usuario elija una de las estructuras disponibles (un selector de estructura).

Por ejemplo, cuando se configura el ETA, es importante que el usuario pueda elegir una estructura para el destino del ETA. De manera similar, un usuario podría tener dos detectores de humo en la "sala de estar" de dos casas diferentes. Si necesitas correlacionar la estructura con tu concepto de casa, te recomendamos que lo hagas durante el proceso de autorización.
Obtén más información sobre cómo los usuarios administran los dispositivos en varias estructuras.
Máximos de dispositivos
Existen límites para la cantidad de dispositivos que admite Nest en una estructura.
Tipo de dispositivo | Máximo por estructura |
---|---|
Nest Thermostat | 20 |
Cámaras Nest | 10 |
Nest Protect | 18 |
Mensajes de error
Para obtener más información sobre qué significan los errores de llamada a la API y cómo manejarlos, consulta Mensajes de error.