In this Codelab, you'll go through the entire Works with Nest integration process, covering all the basics of connecting to the Nest API.

What you'll learn

What you'll need

Nest Home Simulator

To simulate a Nest Thermostat in this Codelab, use the Nest Home Simulator Chrome extension.

Download Nest Home Simulator

Postman

To easily make OAuth and API calls in this Codelab, use the Postman app. It is available as either a Chrome extension or a native app.

Download Postman

Postman can translate API calls into a number of languages, so you can tailor it to your specific integration.

To create a Works with Nest integration, first create a product in the developer console:

  1. Sign in with an existing account, or register as a new developer at https://console.developers.nest.com/nl/auth/new. Validate your email address so you can create a product.
  2. Select CREATE A CLOUD PRODUCT. Fill out all required fields with any values you like. Leave the Redirect URI field blank.
  3. Select the Thermostat read/write permission and fill in its description. Since this is a test integration, you don't necessarily have to provide a complete description, but it's good to get into the habit of doing so.

Once your product is created, it's available for selection from the main Products page.

A successful WWN integration requires a developer product and an end-user device. This device can be a Nest Thermostat, a Nest Protect, or a Nest Cam. For this Codelab, you will use Nest Home Simulator to simulate a Thermostat.

User account

Register as a user at https://home.nest.com. This is where you view Nest devices as an end user. You can use the same email address and password as your developer account, if you prefer.

When you first sign in, you'll be asked to set up your home as if it were a real location. Use whatever information you like. Once complete, open Nest Home Simulator and sign in with those same user credentials.

Create a device

In Nest Home Simulator, select ADD THERMOSTAT in the Properties section to add a virtual Thermostat. The device appears in your Home on the user site. You now have a Thermostat that can be used to authorize a WWN product integration.

The Works with Nest API uses OAuth 2.0 for authorization. In this step you'll get the access token that you'll use for all future API calls.

For this Codelab, we will authorize using the PIN option. To do so, make sure the Redirect URI field on the Product page is empty before going through the authorization flow.

Select your Product on the main Products page in the developer console, and go to the Overview tab:

In the OAuth section there are three values:

To authorize using a PIN, copy the Authorization URL and paste it into a browser window. A prompt requesting access appears:

Select ACCEPT. A PIN (this is your Authorization Code) is displayed:

You now have all the information you need to make a call for an access token. Open Postman and make a POST call to the authorization endpoint, using your specific Authorization Code, Product ID, and Product Secret values:

  1. Select POST from the command drop-down
  2. Enter https://api.home.nest.com/oauth2/access_token as the URL
  3. Select the Body grouping and choose x-www-form-urlencoded
  4. Add the following keys:

KEY

VALUE

client_id

Your Product's Product ID value

client_secret

Your Product's Product Secret value

grant_type

authorization_code

code

The Authorization Code (PIN)

In Postman it looks like this:

Send the POST request. This returns a JSON with the access token:

{
  "access_token": "c.kO3iIWtVFywdlh...",
  "expires_in": 315360000
}

Make a copy of the access token. You'll need it for all subsequent calls to the API endpoint (https://developer-api.nest.com). We'll be using REST to make the calls in this Codelab.

Now that you have an access token, let's make sure it works. Using Postman, perform a GET call to the REST endpoint:

  1. Select GET from the command drop-down
  2. Enter https://developer-api.nest.com as the URL
  3. Select the Header grouping and add the following keys:

KEY

VALUE

Content-Type

application/json

Authorization

Access token with a prefix of "Bearer":

Bearer c.kO3iIWtVFywdlh...

In Postman it looks like this:

Authorization is always Bearer access-token. Unless you reauthorize the WWN connection, the keys will remain the same for all subsequent calls to the API.

When all required information is entered in Postman, Send the GET request. This returns a JSON with all the structures and devices in the home, along with account metadata (access token and client version).

{
  "devices": {
    "thermostats": {
      "4zWYGlpfn0bwluRlV-adbawOEGhwC6HI": {
        "humidity": 50,
        "locale": "en-US",
        "temperature_scale": "F",
        "is_using_emergency_heat": false,
        "has_fan": true,
        "software_version": "5.6.1",
        "has_leaf": true,
        "where_id": "ys8L-1yqXSMo9Od1qDAZ_Oy_g6IJ_6PpFpLZtKOaeGEW3nsAkB46Gw",
        "device_id": "4zWYGlpfn0bwluRlV-adbawOEGhwC6HI",
        "name": "Hallway (F345)",
        "can_heat": true,
        "can_cool": true,
        "target_temperature_c": 20,
        "target_temperature_f": 68,
        "target_temperature_high_c": 26,
        "target_temperature_high_f": 79,
        "target_temperature_low_c": 19,
        "target_temperature_low_f": 66,
        "ambient_temperature_c": 21,
        "ambient_temperature_f": 70,
        "away_temperature_high_c": 24,
        "away_temperature_high_f": 76,
        "away_temperature_low_c": 12.5,
        "away_temperature_low_f": 55,
        "eco_temperature_high_c": 24,
        "eco_temperature_high_f": 76,
        "eco_temperature_low_c": 12.5,
        "eco_temperature_low_f": 55,
        "is_locked": false,
        "locked_temp_min_c": 20,
        "locked_temp_min_f": 68,
        "locked_temp_max_c": 22,
        "locked_temp_max_f": 72,
        "sunlight_correction_active": false,
        "sunlight_correction_enabled": true,
        "structure_id": "sqYZeSEILKH3MoYBCWrda-6oiOUfeTFeQyW6mF_RZw9HDicCb-RIcw",
        "fan_timer_active": false,
        "fan_timer_timeout": "1970-01-01T00:00:00.000Z",
        "fan_timer_duration": 15,
        "previous_hvac_mode": "",
        "hvac_mode": "heat",
        "time_to_target": "~0",
        "time_to_target_training": "ready",
        "where_name": "Hallway",
        "label": "F345",
        "name_long": "Hallway Thermostat (F345)",
        "is_online": true,
        "hvac_state": "off"
      }
    }
  },
  "structures": {
    "sqYZeSEILKH3MoYBCWrda-6oiOUfeTFeQyW6mF_RZw9HDicCb-RIcw": {
      "name": "NestTest",
      "country_code": "US",
      "time_zone": "America/Los_Angeles",
      "away": "home",
      "thermostats": [
        "4zWYGlpfn0bwluRlV-adbawOEGhwC6HI"
      ],
      "structure_id": "sqYZeSEILKH3MoYBCWrda-6oiOUfeTFeQyW6mF_RZw9HDicCb-RIcw",
      "wheres": {
        ...
        }
    }
  },
  "metadata": {
    "access_token": "c.kO3iIWtVFywdlh...",
    "client_version": 1
  }
}

Read a portion of the API

Calls to the root API endpoint are useful for:

However, as part of an integration, you're more likely to perform a read call for an individual value. It's a best practice to only ask for the data you need.

Let's get the humidity of the Thermostat. Using the root API endpoint and the JSON output above, we can construct the following URL:

https://developer-api.nest.com/devices/thermostats/4zWYGlpfn0bwluRlV-adbawOEGhwC6HI/humidity

Now make the same GET call in Postman, using that URL. Remember to always replace the device_id in the URL with the unique value from your JSON output:

https://developer-api.nest.com/devices/thermostats/<your-thermostat-device-id>/humidity

This call simply returns the value of the field:

50

Adjust the URL based on the full JSON object to return whichever objects or values you like. Feel free to try out a few other read calls before moving on.

Let's say you want to change the target temperature on your Nest Thermostat. To do this, specify the field and desired value as part of the API call.

Target temperature is exposed in two fields:

Both fields are tied to the target temperature displayed on a Thermostat. Changing either of them changes the target temperature accordingly, but make sure to write the proper value to the correct endpoint. For example, if you want to change the temperature to 20 degrees Celsius, do not write a value of 20 to the target_temperature_f endpoint (this results in a Temperature F value is too low error).

Using Postman, perform a PUT call to the REST endpoint:

  1. Select PUT from the command drop-down
  2. The URL should go to the parent level of the target value. In this example it's the Thermostat device ID: https://developer-api.nest.com/devices/thermostats/<your-thermostat-device-id>
  3. The Header grouping contains the same keys as the GET (read) calls from the previous step:

KEY

VALUE

Content-Type

application/json

Authorization

Access token with a prefix of "Bearer":

Bearer c.kO3iIWtVFywdlh...

  1. Select the Body grouping, then select raw for the type
  2. In the text box beneath that, enter the key-value pair for what you'd like to update, in the following format: {"target_temperature_f": 65}

In Postman it looks like this:

Send the PUT request. If successful, you'll get a JSON response with confirmation of the new value, and the target temperature on your Thermostat will change to 65℉.

{
  "target_temperature_f": 65
}

Write to multiple fields

You can write to multiple fields in a single PUT call. To do so, separate the key-value pairs by a comma:

{"target_temperature_f": 70, "temperature_scale": "C"}

Note that some fields are integers, while some are strings. Make sure to format each value appropriately.

Check the API Reference for more information on field data types.

You've just gone through the entire Works with Nest integration process. You now know the basics of how to connect to the Nest API. Easy, huh?

What we've covered

Next Steps

To learn more, explore these WWN references: