The Nest API models a physical home or building as a structure, with Nest Learning Thermostats, Nest Protects, and Nest Cams as devices in the structure. This structure also contains information about the home as a whole (such as Away or ETA state, or active Rush Hours).
Every data element in the structure is addressable by a resource URL (called "data locations") in a shared JSON document. Each data location can store strings, numbers, booleans, parent/child objects, or arrays.
Explore the data model with this interactive API Reference.
From the API, you can sync data from locations at multiple levels in the data model, for example:
- an entire structure, including all devices
- a single device in a structure
- a group of data values (current and ambient temperature)
- a single data value (battery health state)
Your products should respond thoughtfully to events like these:
- presence (home and away)
- safety (smoke and carbon monoxide)
- energy use during expensive times of day
- events (sound and motion)
However, keep in mind that each of the device-based objects are working under real-world constraints. For example, the thermostat should not run the air conditioner when emergency heat is enabled. Our API is designed to safeguard both our devices and the user's home, and will prevent certain actions if they would be surprising or dangerous.
Permissions and shared device data
The ability to read or write to a data location is controlled by permissions. Permission groups provide read, write, or read/write access to selected data values in devices and structures.
For more info, see the Permissions Overview.
Data and privacy
The data involved with home products can be very personal. Home sensor data contains information about how people live their lives in their personal space. The security and handling of that data is very important, and a significant focus at Nest. We make it crystal clear to users what kind of data we have, how it's used, and where they can control it.
Learn more about our views on privacy.
Metadata
Metadata is additional information that is provided when you make a call to the root-level endpoint:
https://developer-api.nest.com/
access_token
After user authorization, your product uses an access token to make API calls to the Nest service. This access token serves as proof that a user has authorized your product to make calls on their behalf.
| Details | |
|---|---|
| Returns | stringExample: "c.FmDPkzyzaQe..." |
client_version
Client version is the last user-authorized version of a client, and is
associated with an access_token.
When you update the permissions for a client, the client version is incremented, and the user is notified that an update is available. Your users must accept this client update before they can use your updated product.
| Details | |
|---|---|
| Returns | numberExamples: 1, 17, 42 |
user_id
The user ID allows you to identify users across API calls. This identifier differs for each Works with Nest product and user combination.
For example, if user 1 has authorized Works with Nest product A and Works
with Nest product B, then product A has one user_id value for user 1,
and product B has a different user_id value for user 1.
| Details | |
|---|---|
| Returns | stringExample: z.1.1.7DHps... |