The Architecture of the Nest API

About the Nest service

Nest applications allow users to connect with their home from wherever they may be. All Nest devices (Thermostats, Protects, and Cameras) and applications (iOS, Android, and web apps) connect to the Nest service.

Example cloud-to-cloud

The Nest service provides a data model of the home. Devices and applications read from this data model to take appropriate action. They update the data model to reflect changes in the system.

For example, a thermostat reads its target temperature from the data model. It sets the ambient temperature to its current measurement, and sends sensor data to Home/Away Assist, which adjusts the structure mode accordingly.

Nest devices operate in constrained environments. Power is limited and home network connectivity can be unreliable. Your products and services can leverage our device algorithms to offer users a simple, intuitive home experience.

The data model

The Nest API is represented as a JSON document with top-level attributes of metadata, devices, and structures. Your Works with Nest products use this JSON document to interact with, and react to, Nest devices and related state changes.

Nest structures represent physical structures in the real world. They serve as an organizing point for devices and store data for the building as a whole. Typically, a structure is a user home.

Nest devices represent physical devices (Thermostats, Protects, and Cameras) within a structure.

Every data element in the JSON document is addressable by URL (also known as "data locations"). Works with Nest products can read and write to sections of this document and subscribe to changes. This subscription capability allows Works with Nest products to react in real time to changes made to the system, such as turning off lights when a user sets the structure to Away.

Objects also work under real-world constraints. The data model safeguards devices and the user's home by preventing surprising and dangerous actions. For example, the thermostat doesn't run the air conditioner when emergency heat is enabled.

Explore the data model with this interactive API Reference.

Intended state

The Nest service stores the authoritative state of the system, and Works with Nest products subscribe to changes. Modifying this state (for example, to change a thermostat's target temperature) causes the service to push a change notification to all subscribers.

Because this propagation has some delay and networks can be unreliable, the state observed by a product may not be the state currently observed by other products or the service. State is eventually synchronized as messages are transmitted between various products.

This document-oriented publish/subscribe model provides responsive application interactions.

Using the Nest service

The Nest service runs on a Firebase server that supports both REST and WebSocket endpoints. In this model your product is the client, and the Nest service is the server.

To access the REST endpoints, you need to use HTTPS in your product. There are many third-party client libraries that can be used for this purpose.

To access the WebSocket endpoints, you need to use a Firebase SDK in your product. SDKs are available for Web, iOS, or Android applications.

Functionality and performance differs between clients and endpoints:


Client

Read

Write
Data Rate Limiting
applied on:
Recommended
connection
REST Polling Yes Read and Write calls Cloud-to-Cloud
REST Streaming Subscription No Read calls App-to-Cloud
Cloud-to-Cloud
Firebase SDK Subscription Yes Write calls App-to-Cloud

REST Streaming is the preferred method for single clients connecting directly to the Nest service. It provides real-time updates on device and structure state changes compared to REST, where the state must be explicitly polled for.

For Cloud-to-Cloud integrations with more than 50 users, we recommend using Multiplex.

Permissions and authorization

We want to allow developers to build products and services that make homes better, without compromising user privacy and security. All of our communications are secure, and permission to access data is always explicitly granted by the user. For more information, see the Permissions Overview.

Authorization is handled by the OAuth 2.0 protocol. When a user agrees to provide access to the requested permission level, Nest authenticates the request and an access token is granted to the requestor. That access token can be used to access the Nest API and interact with the user's structures and devices.

Granting an access token establishes a trust relationship between a user, a Works with Nest product, and Nest. Users can revoke access at any time.

To learn how to authorize a product, see the Authorization Overview.