search

gboudreau / nest-api

Unofficial Nest Learning Thermostat API
GNU Lesser General Public License v3.0
299 stars 92 forks source link
api nest php

readme

Unofficial Nest Learning Thermostat API

This is a PHP class that will allow you to monitor and control your Nest Learning Thermostat, and Nest Protect.

Note that since I started this, Nest have started an official Developer program. You might be better served using the official APIs, versus this PHP class here in which you need to store your credentials in plain text, and which use the non-supported APIs used by the mobile & web apps.
i.e. if you're building a serious commercial application, go sign-up into Nest's Developer program. If you just want to build something for yourself, then you're probably fine with this PHP class here.

Features

Usage

You can just download nest.class.php and require/include it, or use composer: require "gboudreau/nest-api": "dev-master".

See examples.php for details, but here's a Quick Start.

<?php

require_once('nest.class.php');

// Use a Nest account:
$username = 'you@gmail.com';
$pasword = 'Something other than 1234 right?';
$nest = new Nest($username, $pasword);

// Or use a Google account (see instructions below on how to find those values):
$issue_token = 'https://accounts.google.com/o/oauth2/iframerpc?action=issueToken&response_type=token%20id_token&login_hint=UNIQUE_VALUE_HERE&client_id=733249279899-44tchle2kaa9afr5v9ov7jbuojfr9lrq.apps.googleusercontent.com&origin=https%3A%2F%2Fhome.nest.com&scope=openid%20profile%20email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fnest-account&ss_domain=https%3A%2F%2Fhome.nest.com';
$cookies = '#YOUR_COOKIES_HERE#'; // All on one line; remove any new-line character you might have
$nest = new Nest(NULL, NULL, $issue_token, $cookies);

// Get the device information:
$infos = $nest->getDeviceInfo();
print_r($infos);

// Print the current temperature
printf("Current temperature: %.02f degrees %s\n", $infos->current_state->temperature, $infos->scale);

// Cool to 23
$nest->setTargetTemperatureMode(TARGET_TEMP_MODE_COOL, 23.0);

// Set Away mode
$nest->setAway(TRUE);

// Turn off Away mode
$nest->setAway(FALSE);

Example output for getDeviceInfo():

{
  "current_state": {
    "mode": "range",
    "temperature": 24.09999,
    "humidity": 42,
    "ac": false,
    "heat": false,
    "fan": true,
    "auto_away": 0,
    "manual_away": false,
    "leaf": false,
    "battery_level": 3.948
  },
  "target": {
    "mode": "range",
    "temperature": [
      23,
      26
    ],
    "time_to_target": 0
  },
  "serial_number": "01AB02BA117210S5",
  "scale": "C",
  "location": "1061f350-a2f1-111e-b9eb-123e8b139117",
  "network": {
    "online": true,
    "last_connection": "2012-09-30 21:26:25",
    "wan_ip": "173.246.19.71",
    "local_ip": "192.168.1.201",
    "mac_address": "18b430046194"
  }
}

Use try...catch to catch exceptions that could occur:

try {
    $nest = new Nest(NULL, NULL, $issue_token, $cookies);
    // Execute all Nest-related code here
} catch (UnexpectedValueException $ex) {
    // Happens when the issue_token or cookie is not working, for whatever reason
    $error_message = $ex->getMessage();
    mail(...);
} catch (RuntimeException $ex) {
    // Probably a temporary server-error
} catch (Exception $ex) {
    // Other errors; should not happen if it worked in the past
}

// Continue your code here, for example to save the result in a database

Using a Google Account

The values of $issue_token, and $cookies are specific to your Google Account. To get them, follow these steps (only needs to be done once, as long as you stay logged into your Google Account).

Troubleshooting

If you have any issues, try adding this at the top of your PHP script, to ask PHP to echo all errors and warnings.

error_reporting(E_ALL);

Acknowledgements

Developed mainly using a free open-source license of PHPStorm kindly provided by JetBrains. Thanks guys!