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 shouldn't 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 product 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

Part of user authorization, your product will use 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 product, and is associated with an access_token.

When you update the permissions in a product, the client version is incremented, and the user is notified that an update is available. Your users must accept the product update before they can use your new 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 client and user combination.

For example, if user 1 has authorized Works with Nest client A and Works with Nest client B, then client A has one user_id for user 1, and client B has a different user_id for user 1.

Details
Returnsstring
Example: z.1.1.7DHps...