Skip to main content

Python API and command line tool for talking to the Nest™ Thermostat

Project description


[sudo] pip install python-nest



You can import the module as nest.

import nest

username = ''
password = 'swordfish'

napi = nest.Nest(username, password)

for structure in napi.structures:
    print 'Structure %s' %
    print '    Away: %s' % structure.away
    print '    Devices:'

    for device in structure.devices:
        print '        Device: %s' %
        print '            Temp: %0.1f' % device.temperature

# The Nest object can also be used as a context manager
with nest.Nest(username, password) as napi:
    for device in napi.devices:
        device.temp = 23

# Weather data is also availible under structure or device
# The api is the same from either

structure = napi.structures[0]
time_str ='%Y-%m-%d %H:%M:%S')
print 'Current Weather at %s:' % time_str
print '    Condition: %s' %
print '    Temperature: %s' %
print '    Humidity: %s' %
print '    Wind Dir: %s' %
print '    Wind Azimuth: %s' %
print '    Wind Speed: %s' %

# NOTE: Hourly forecasts do not contain a "contidion" its value is `None`
#       Wind Speed is likwise `None` as its generally not reported
print 'Hourly Forcast:'
for f in
    print '    %s:' % f.datetime.strftime('%Y-%m-%d %H:%M:%S')
    print '        Temperature: %s' % f.temperature
    print '        Humidity: %s' % f.humidity
    print '        Wind Dir: %s' % f.wind.direction
    print '        Wind Azimuth: %s' % f.wind.azimuth

# NOTE: Daily forecasts temperature is a tuple of (low, high)
print 'Daily Forcast:'
for f in
    print '    %s:' % f.datetime.strftime('%Y-%m-%d %H:%M:%S')
    print '    Condition: %s' %
    print '        Low: %s' % f.temperature[0]
    print '        High: %s' % f.temperature[1]
    print '        Humidity: %s' % f.humidity
    print '        Wind Dir: %s' % f.wind.direction
    print '        Wind Azimuth: %s' % f.wind.azimuth
    print '        Wind Speed: %s' %

# NOTE: By default all datetime objects are timezone unaware (UTC)
#       By passing `local_time=True` to the `Nest` object datetime objects
#       will be converted to the timezone reported by nest. If the `pytz`
#       module is installed those timezone objects are used, else one is
#       synthesized from the nest data
napi = nest.Nest(username, password, local_time=True)
print napi.structures[0].weather.current.dateimte.tzinfo

In the API all temperature values are in degrees celsius. Helper functions for conversion are in the utils module:

from nest import utils as nest_utils
temp = 23.5
fahrenheit = nest_utils.c_to_f(temp)
temp == nest_utils.f_to_c(fahrenheit)

The utils function use decimal.Decimal to ensure precision.

For “advanced” usage such as token caching, use the source, luke!

Command line

usage: nest [-h] [--conf FILE] [--token-cache TOKEN_CACHE_FILE] [-t TOKEN]
            [-u USER] [-p PASSWORD] [-c] [-s SERIAL] [-i INDEX]
            {temp,fan,mode,away,target,humid,target_hum,show} ...

Command line interface to Nest™ Thermostats

positional arguments:
                        command help
    temp                show/set temperature
    fan                 set fan "on" or "auto"
    mode                show/set current mode
    away                show/set current away status
    target              show current temp target
    humid               show current humidity
    target_hum          show/set target humidity
                            specify target humidity value or auto to auto-select a
                            humidity based on outside temp
    show                show everything

optional arguments:
  -h, --help            show this help message and exit
  --conf FILE           config file (default ~/.config/nest/config)
  --token-cache TOKEN_CACHE_FILE
                        auth access token
  -t TOKEN, --token TOKEN
                        auth access token cache file
  -u USER, --user USER  username for
  -p PASSWORD, --password PASSWORD
                        password for
  -c, --celsius         use celsius instead of farenheit
  -s SERIAL, --serial SERIAL
                        optional, specify serial number of nest thermostat to
                        talk to
  -i INDEX, --index INDEX
                        optional, specify index number of nest to talk to

    nest --user --password swordfish temp 73
    nest --user --password swordfish fan auto
    nest --user --password swordfish target_hum 35

A configuration file can also be specified to prevent username/password repitition.

user =
password = swordfish
token_cache = ~/.config/nest/cache

The [DEFAULT] section may also be named [nest] for convience.


This module was originally a fork of nest_thermostat <> which was a fork of pynest <

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-nest-2.2.tar.gz (9.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page