Nest API Reference

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:

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.

Permission version

When we introduce new permissions to the data model, we increment the permission version number. In order to take advantage of these new features, you should update your client with new permissions for the data you want to access. You'll find permission version numbers associated with each data value.

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
Returnsstring
Example: "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.

For more info, see Manage Client Version.

Details
Returnsnumber
Examples: 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
Returnsstring
Example: z.1.1.7DHps...