
As estruturas do Nest representam estruturas físicas no mundo real. Normalmente, a casa de um usuário serve como um ponto de organização para os dispositivos e armazena dados aplicáveis a toda a casa.
A API Nest fornece acesso aos seguintes dados no nível da estrutura, dependendo do nível de permissões concedidas:
- Nome da estrutura e do dispositivo "onde nome" (local na casa)
- Lista de dispositivos na casa
- Status do evento de energia (hora de pico de energia)
- Estado "Ausente"
- HEC do usuário
- Estado de segurança
- Código postal ou CEP
Alguns recursos no nível da estrutura são abordados em guias de API separados e mais detalhados:
- Ausente e HEC: estado "Ausente", HEC do usuário
- Energy: status de evento de energia
- Segurança: segurança e impedimento
Permissões da estrutura
Para acessar... | Selecionar... |
---|---|
A maioria dos valores de dados no objeto structures |
Permissões Ausente, ETA, Energia ou Código postal |
O valor de dados name no objeto structures |
Permissão de leitura/gravação da estrutura |
Veja como as permissões funcionam na Referência da API interativa.
Identificadores da estrutura
Nome
O nome da estrutura assume como padrão "Home", mas pode ser qualquer string escolhida pelo
usuário. Ao escolher a permissão
Estruturar leitura/gravação, você pode alterar a estrutura name
.
Onde
wheres
é um objeto definido em uma estrutura que contém identificadores de localização (where_id
e name
). Use wheres
para criar nomes de locais personalizados ou acessar
nomes de locais padrão.
O acesso ao objeto wheres
requer as permissões Camera, Smoke+CO Alarm ou Thermostat.
where_id
- Um identificador exclusivo gerado pelo Nest que representa
name
. where_id
é somente leitura e é criado automaticamente na chamada para criar um personalizado em quename
.
name
- O nome de exibição do dispositivo. Pode ser qualquer nome de ambiente de uma lista fornecida ou um nome personalizado.
- Para criar um personalizado em que
name
, faça uma chamada POST para escrever um novo e personalizado em quename
. Owhere_id
é retornado na chamada - Considerações
- Não é possível editar ou excluir
name
após a criação name
precisa ser exclusivo na estrutura- Se um dispositivo estiver pareado com uma estrutura, o personalizado em que
name
associado ao dispositivo vai poder ser acessado pelo caminho/structures/
- Para mover um dispositivo com um personalizado em que
name
para uma estrutura diferente, pareie o dispositivo e pareie novamente com o nome desejado.
- Não é possível editar ou excluir
Saiba mais sobre os nomes da Nest Thermostats, Nest Protects e Nest Cams.
Outros metadados
Todos os valores de dados são somente leitura, a menos que seja especificado de outra forma.
Valor dos dados | Descrição |
---|---|
structure_id
|
Uma string que representa exclusivamente essa estrutura. Todos os desenvolvedores verão um ID diferente para a mesma estrutura, mas vários produtos do mesmo desenvolvedor verão o mesmo código. |
country_code
|
Um código de país ISO 3166-1 alfa-2 que mapeia para o local registrado da estrutura |
postal_code
|
CEP ou código postal, dependendo do país |
time_zone
|
Uma string de fuso horário da IANA (em inglês) que é mapeada para o fuso horário da estrutura. |
Recursos de estrutura
Estados de alarme de fumaça e monóxido de carbono
Ao escolher a permissão de leitura do Smoke+CO, é possível acessar smoke_alarm_state
e co_alarm_state
no objeto structures
.
Esses mesmos valores de dados também estão disponíveis no objeto de dispositivo
(devices/smoke_co_alarms
).
Consulte o guia de alarme do Smoke+CO para saber mais sobre esses estados.
Restrições relacionadas à estrutura
Muitos valores de dados funcionam juntos para determinar como os dispositivos se comportam em uma estrutura.
- Quando um estado
away
da estrutura estiver definido comoaway
, a palavra "ECO" será exibida no Nest Thermostat no idioma preferido do usuário - Quando um estado
away
da estrutura é definido comoaway
, é possível:- Definir
fan_timer_active
- mudar
target_temperature_f
outarget_temperature_c
- Definir
- Quando um estado
away
da estrutura é definido comohome
, é possível:- Fazer uma chamada de HEC (definir o ID da viagem e o horário de chegada)
- Quando a desativação
de emergência
está ativa, não é possível definir
fan_timer_active
. - Quando o aquecimento de emergência
está ativado, não é possível definir a estrutura como
away
Várias estruturas
É possível que um usuário tenha mais de uma estrutura anexada à conta do Nest. Por isso, o produto precisa oferecer um meio para o usuário escolher entre as estruturas disponíveis (um seletor de estrutura).

Por exemplo, ao definir o ETA, é importante que o usuário possa escolher uma estrutura para o destino do ETA. De maneira semelhante, um usuário pode ter dois detectores de fumaça na "sala de estar" de duas casas diferentes. Se você precisar fazer correlação de estrutura com seu próprio conceito de casa, recomendamos que faça isso durante o processo de autorização.
Saiba como os usuários gerenciam dispositivos em várias estruturas.
Máximo de dispositivos
Há limites para quantos dispositivos o Nest oferece suporte em uma estrutura.
Tipo de dispositivo | Máximo por estrutura |
---|---|
Nest Thermostat | 20 |
Câmeras Nest | 10 |
Nest Protect | 18 |
Mensagens de erro
Para mais informações sobre o que significam erros de chamada de API e como lidar com eles, consulte Mensagens de erro.