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.
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
To access the REST endpoints in the Nest service, use HTTPS in your product. There are many third-party client libraries that can be used for this purpose.
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 connection to the Nest API, see the Authorization Overview.