About the Nest API

What you need to know

The Nest API is a near real-time data API, offering subscription-based access to data shared by Nest devices. With the Nest API, you can build clients that access Nest device data, and get the ability to read or write shared data values.

Learn more about how it works, use cases, the tools you get and tips for success.

How it works

How the Nest API worksWhen you build Works with Nest (WWN) products, you'll use Firebase client libraries to subscribe to data values via the Nest API. When a subscribed data value changes, the new data values are updated in real time, and stored as a standard JSON document. Your client can then update a display or trigger an action, based on the subscribed data.

In cases where the platform you're using has no available Firebase library, consider REST Streaming or REST instead.
Get started and build WWN products >

Use cases

With the Nest API, you can access data and set controls on Nest devices in the home:

Nest Learning Thermostat
  • View current temperature
  • View or set target temperature
  • Set fan timer
  • View or set temperature mode
  • View humidity
  • View online status and last connection information
Nest Protect
  • View CO or smoke status
  • View battery health state
  • View last manual test status and timestamp for last manual test
  • View online status and last connection information
Home
  • View a list of devices in the home
  • View energy event status (Rush Hour Rewards)
  • View or set Away state
  • View postal or zip code
  • Set ETA
  • Write your product data to the Nest service with the Resource Use API and share your energy savings in the Nest Home Report

See the API Reference to explore the data model >

Example

Let's say you want to create a WWN product for the Nest Learning Thermostat that monitors two values: current temperature and target temperature. To watch for changes in both of these data attributes, you would subscribe to the thermostat object in a structure, then:

  1. When your customer adjusts the temperature at the Nest Thermostat the target temperature changes and the Nest service updates the JSON doc, which is synchronized in real time
  2. Your client listens for changes, then:
    • displays the new target temperature
    • updates the current temperature as it changes

You can subscribe to individual data values or to parent data objects in the hierarchy. When you subscribe to a parent object (structures, thermostats or smoke_co_alarms), you can get all the data values in the object.
Learn more about subscriptions and how to access data locations by URL >

Tools you get

When you develop with the Nest API, you'll get these resources:

  • API reference, an interactive tool to explore the API data model
  • Home Simulator, a testing tool that simulates device states and behaviors
  • Sample code, code you can use to try out simple web, iOS and Android apps

Tips for success

Learn more about the API features you'll use to build successful WWN products:

Shared device data and access control

Works with NestPermissions grant read or write access to different values in the data model. You'll choose the permissions that make sense for your client.

Your customers will see these permissions when they grant your client access to their Nest device data.
Learn more about permissions and shared data values >

Permission to access data is always explicitly granted by the user. Users can revoke access at any time.

Data architecture

Every value in the data model is addressable by URL. These data locations can store strings, numbers, booleans, objects or arrays. From the API, you can sync data from locations at multiple levels in the hierarchy.
Learn more about data structure and access >

User authorization

User authorization gives your customers a secure means to give you access to their Nest device data.

We offer both web-based and PIN-based authorization. PIN-based authorization is generally used for devices with no web UI and that have a numeric keypad interface.

Security protocol

We use OAuth 2.0 for authorization. OAuth is a means to securely create a trust agreement between a resource owner (a Nest user), a client (a product or service developed by a Nest developer) and a resource server (Nest's API servers).

Technical requirements for developers

You should have knowledge of common programming languages, platforms, authorization and communication protocols, such as:

  • Programming languages: Java, Objective-C, JavaScript
  • Platforms: iOS, Android, web, Mac OS, Windows, Linux, Rails, Django
  • Server-side JavaScript/Java programming
  • OAuth 2.0 (authentication)
  • Firebase (client libraries used by the Nest API)

Guidelines and compliance

When you register for the Nest Developer Program we'll ask you to agree to the Developer Program Terms of Service.

When you're ready to launch your product, you'll submit your WWN product for a client review, so we can be sure that you're providing a great user experience and that you're using the Nest brand assets properly.

We'll also conduct a Marketing review to check that you're promoting your WWN product in compliance with the Nest Marketing Guidelines.

After you pass client and marketing review, you can launch your product as an official Works with Nest partner.

If you fail to comply with these agreements, we have the right to suspend your developer account, close all active sessions and revoke all access tokens.