
Use the Nest API to listen for changes on structures and devices, so you can take steps to conserve energy when the homeowners are away, notify them that something is amiss (for example, the garage door is open), or activate features to make the home more comfortable and welcoming.
This guide shows how to read data from Nest devices and structures. To learn how to make write calls, see API Write Examples.
Prerequisites
Before making API calls, obtain an access token, as described in Authenticating with OAuth 2.0.
About REST read calls
For REST calls, use GET to read data.
REST read calls are useful is limited scenarios, such as the following use cases:
- Ad-hoc one-off calls
- Proof-of-concept labs
- Troubleshooting
- Apps that poll approximately every minute
- Refresh button implementations
REST read calls are not useful for continuous real-time or streaming scenarios.
Bearer authentication
We recommend compliance with the
OAuth standard,
which offers increased security by using "Bearer"
authentication to
transmit the access token. Calls with client credentials in the URL are not
recommended.
The "Content-Type"
header directs the server to use JSON.
The "Authorization"
header provides API access.
Examples
In the following examples, replace YOUR_TOKEN_HERE
with your specific access token, such as "c.twC2q...".
Read structures and devices
To read all the structure and device data (base level), use the root-level URL. For more granular responses, modify the URL as needed.
curl -v --location-trusted \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -X GET "https://developer-api.nest.com/"
curl -v --location-trusted \ -H "Accept: text/event-stream" \ -H "Authorization: Bearer LIST_OF_ACCESS_TOKENS" \ -X GET "https://developer-api.nest.com/multiplex"
package main import ( "errors" "fmt" "io/ioutil" "net/http" ) const token = "YOUR_TOKEN_HERE" // Update with your token func main() { url := "https://developer-api.nest.com/" req, _ := http.NewRequest(http.MethodGet, url, nil) req.Header.Add( "Authorization", fmt.Sprintf("Bearer %s", token), ) customClient := http.Client { CheckRedirect: func(redirRequest *http.Request, via []*http.Request) error { // Go's http.DefaultClient does not forward headers when a redirect 3xx // response is received. Thus, the header (which in this case contains the // Authorization token) needs to be passed forward to the redirect // destinations. redirRequest.Header = req.Header // Go's http.DefaultClient allows 10 redirects before returning an // an error. We have mimicked this default behavior. if len(via) >= 10 { return errors.New("stopped after 10 redirects") } return nil }, } response, _ := customClient.Do(req) if response.StatusCode != 200 { panic(fmt.Sprintf( "Expected a 200 status code; got a %d", response.StatusCode, )) } defer response.Body.Close() body, _ := ioutil.ReadAll(response.Body) fmt.Println(string(body)) }
"use strict" var request = require('request'); var token = "YOUR_TOKEN_HERE"; // Update with your token var url = "https://developer-api.nest.com"; var options = { "method": "GET", "path": "/", "headers": { "Authorization": "Bearer " + token }, "followRedirect": true }; var req = request(url, options, function(err, resp, data) { console.log('response code: ' + resp.statusCode); if (err) { console.log('Error: ' + err.message); } console.log("data: " + data); }); req.end();
To use the Node.js code example, install the request module (https://www.npmjs.com/package/request).
npm install request
import hashlib import json import os import requests url = "https://developer-api.nest.com/" token = "YOUR_TOKEN_HERE" # Update with your token headers = {'Authorization': 'Bearer {0}'.format(token), 'Content-Type': 'application/json'} response = requests.get(url, headers=headers, allow_redirects=False) if response.status_code == 307: response = requests.get(response.headers['Location'], headers=headers, allow_redirects=False) print(response.text)
import http.client from urllib.parse import urlparse token = "YOUR_TOKEN_HERE" # Update with your token conn = http.client.HTTPSConnection("developer-api.nest.com") headers = {'authorization': "Bearer {0}".format(token)} conn.request("GET", "/", headers=headers) response = conn.getresponse() if response.status == 307: redirectLocation = urlparse(response.getheader("location")) conn = http.client.HTTPSConnection(redirectLocation.netloc) conn.request("GET", "/", headers=headers) response = conn.getresponse() if response.status != 200: raise Exception("Redirect with non 200 response") data = response.read() print(data.decode("utf-8"))
import java.io.IOException; import okhttp3.Headers; import okhttp3.OkHttpClient; import okhttp3.OkHttpClient.Builder; import okhttp3.Request; import okhttp3.Response; import okhttp3.Authenticator; import okhttp3.Route; public class ReadNest { public static void main(String[] args) throws IOException { String auth = "Bearer YOUR_TOKEN_HERE"; // Update with your token OkHttpClient client = new OkHttpClient.Builder() .authenticator(new Authenticator() { @Override public Request authenticate(Route route, Response response) throws IOException { return response.request().newBuilder() .header("Authorization", auth) .build(); } }) .followRedirects(true) .followSslRedirects(true) .build(); Request request = new Request.Builder() .url("https://developer-api.nest.com") .get() .addHeader("content-type", "application/json; charset=UTF-8") .addHeader("authorization", auth) .build(); try { System.out.println("Begin request: "); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); System.out.println("End request"); System.out.println(); Thread.sleep(2 * 1000); } catch (InterruptedException e) { e.printStackTrace(); } } }
To use the Java code example:
1. Download the latest okhttp and okio Jar files at http://square.github.io/okhttp/. Additionally, download the Kotlin stdlib file at https://mvnrepository.com/artifact/org.jetbrains.kotlin/kotlin-stdlib if your version of okhttp depends on it.
2. Construct your code.
3. Compile and run the program with the following class-path settings.
Substitute your library version numbers in the javac and java commands below:
javac -cp .:okhttp-<ver>.jar:okio-<ver>.jar ReadNest.java
java -cp .:okhttp-<ver>.jar:okio-<ver>.jar:kotlin-stdlib-<ver>.jar ReadNest
For instance, if you have the following versions 3.11.0, 2.1.0, and 1.3.0, your commands would look like this:
javac -cp .:okhttp-3.11.0.jar:okio-2.1.0.jar ReadNest.java
java -cp .:okhttp-3.11.0.jar:okio-2.1.0.jar:kotlin-stdlib-1.3.0.jar ReadNest
Using Postman to test the API
The above Curl call can easily be replicated in Postman.

Use the Code link in Postman to translate a call into different languages as a starting point for further development.