Nest Developers
Home Docs API Explorer Blog Community
Go to Console
Guides Reference Samples Support

About the Nest API

The Nest Developer program provides all the tools you need to design, develop, market, and launch your Works with Nest product.

The Nest API offers subscription-based access to data shared by Nest devices. With the Nest API, your Works with Nest product can interact with and react to this user data.

The purpose of the Nest API is to integrate third-party products with Nest products in the home (structure). A Works with Nest integration:

  1. Uses OAuth 2.0 to receive permission from the end user to gather information from the end user's Nest devices.
  2. Uses the Nest API to gather information from Nest devices.
  3. Uses that information to enhance the features available in your (non-Nest) device or app.

Site Link Purpose
User portal
 https://home.nest.com Manage devices as an end user
Developer portal https://console.developers.nest.com Manage Works with Nest integrations
Access token endpoint https://api.home.nest.com/oauth2/access_token Use for authorization
Works with Nest API endpoint https://developer-api.nest.com Make API calls
Nest Home Simulator https://chrome.google.com/webstore/detail/nest-home-simulator/jmcapoebgeaabepohkchkldlfhchkega Test with simulated structures and devices

Codelabs

Before digging too deeply into the documentation, try out our Codelabs. They guide you through the integration workflow and demonstrate best practices.

Quick Start Codelab

Discover how quick and easy it is to get started with the Nest API. In this Codelab you'll learn how to:

  • Create an OAuth client
  • Simulate Nest devices with the Nest Home Simulator
  • Authorize a Works with Nest connection using OAuth 2.0
  • Read and write data in the Nest API using REST

Try the Quick Start Codelab

10 Tips Codelab and Video Series

Use our Python sample app, along with the 10 Tips Codelab and companion video series to learn how to build some essential elements of a successful Works with Nest integration.

The sample app is based on Python and also uses JavaScript and Jinja templates to demonstrate how to build an integration that follows best practices.

Learn how to:

  • Secure your API credentials
  • Provide a structure picker
  • Listen and update fast
  • Handle Home/Away
  • Include confirmation and error messages
  • Remove cached data
  • Remove camera images
  • Handle deauth and revoked auth

The Codelab and videos walk you through each tip, showing you the important code snippets that do the magic.

Try the 10 Tips Codelab

Developer workflow

Use this information to guide you through the complete Works with Nest development process.

Developer workflow
  1. Learn about the Nest API
  2. Scope your Works with Nest product's use cases
    • Brainstorm use cases
    • Sketch out the UX flow
  3. Design and build your Works with Nest product
  4. Test your Works with Nest product
  5. Submit for product and marketing review
  6. Launch your product with Works with Nest brand assets

Integration workflow

A Works with Nest product integration follows this basic process:

  1. A user chooses to integrates the product with one or more Nest devices
  2. The product requests authorization via OAuth 2.0 to the user's Nest data in the form of discrete permission levels
  3. User accepts authorization and grants permission to the product in the form of an access token
  4. The product uses this access token to access the user's data in the Nest service via the Nest API using a REST, REST Streaming, or Multiplex connection
  5. The product reacts, or makes changes, to Nest structure or device states via the Nest API

Integrations can easily be tested against multiple virtual Nest structures and devices using the Nest Home Simulator.

How it works

Data is stored in the Nest service as a shared JSON document. When a subscribed data value changes, the data values in the Nest service are updated to reflect the new state. Your product can then update a display or trigger an action, based on the new state of the subscribed data.

You can subscribe to individual data values or to parent data objects in the hierarchy. Learn more about subscriptions and how to access data locations by URL

The Nest service can be accessed by a few different methods:

Technology Use cases
REST Ad-hoc one-off calls, proof-of-concept labs, troubleshooting, apps that poll approximately every minute, refresh button implementations
REST streaming Single clients connecting directly to Nest services
Cloud-to-cloud integrations
Multiplex REST streaming Cloud-to-cloud integrations

Sample use case

Example cloud-to-cloud

Let's say you want to create a Works with Nest 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, and then:

  1. Your customer adjusts the temperature on their Nest Thermostat
  2. The target temperature value is updated in the Nest service
  3. Your product is notified of the target temperature change via the Nest API and
    • displays the new target temperature
    • updates the current temperature as it is updated in the Nest service

Developer guides

Our developer guides are split into the following categories to aid in the development process:

Category Contents
APIs How the Nest service works, including in-depth guides for each major category of API functionality
Authorization Provide users with a way to authorize access to their data in the Nest service
REST Access the Nest service with REST
Real-time Access the Nest service with a real-time connection
Account management Manage your developer account and Works with Nest clients
Design What you should incorporate into your Works with Nest product design
Review How we review Works with Nest products for a wider audience
Branding Materials you can use for marketing and branding purposes

Product requirements

Learn more about what's required in the design and development of successful Works with Nest products.

Shared device data and access control

User authorization

Your customers see an explanation of these permissions when they grant your product access to their Nest device data.

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

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 Works with Nest integration (the Works with Nest product), and a resource server (Nest's API servers).

Technical requirements for developers

You should have knowledge of the following:

  • Programming languages, such as: Java, Objective-C, JavaScript, Python
  • Frameworks/Platforms, such as: iOS, Android, Node.js, Django, Flask
  • OAuth 2.0 for data authorization

Supported web browsers

You can access the Nest Developer Portal from these web browsers: Chrome, Firefox, IE, or Safari. If you get unexpected results, check for an update to the latest version of your preferred browser.

Guidelines and compliance

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

When you're ready to launch your product, you'll submit your Works with Nest client for review. Our product review guidelines are available to ensure that your overall product provides a great user experience and uses the Nest brand assets properly.

We'll also conduct a Marketing review to check that you're promoting your Works with Nest product in compliance with our policies.

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