Energy

Use the Nest API to optimize energy savings with your product:

The Nest API is built on the concept of data sharing. Nest shares information about what's happening in the home, which allows your products to respond automatically. Sharing your product's energy usage in return helps Nest get a deeper understanding of everything happening in a customer's home. This allows us to improve the features we offer through the Nest Developer program.

Product details

Energy permissions

For access to Rush Hour Rewards data, select the Energy read permission in your product.

To share your product's energy usage with Nest for inclusion in a user's Nest Home Report, you must:

Energy identifiers

$company

The Resource use API includes a string called $company. This value identifies your company as an entity that can share product data with the Nest service.

As part of company verification, Nest defines a destination data path that is unique to your company and product type(s), in the following format:

$company/$product_type

For example:

ftl_lighting_co/lighting

Use this storage location along with device_id to update resource use data.

Note that $company is found in two places within the API data model: as an object in devices, and as a new array in structures/devices.

Each path has a different purpose:

  • Use the devices/$company path to write your product's resource use data
  • Use the structures/structure_id/devices/$company path to read a list of your devices

Energy features

Rush Hour Rewards

RHR Notification

If a user has paired their Nest Account with a participating energy partner, Nest is notified when a Rush Hour event is scheduled. These are peak demand periods predicted by the energy provider.

If your product uses a significant amount of electricity and has the ability to delay action or run in a low-power mode, consider creating different algorithms to conserve energy during Rush Hour events. Notice of an event ranges from just-in-time to 24 hours in advance.

rhr_enrollment is set to "true" if a user is subscribed to Rush Hour Rewards. For start/stop times of an event, check the peak_period_start_time and peak_period_end_time fields.

If a Nest user is not enrolled in the Rush Hour Rewards program, the peak_period_start_time and peak_period_end_time fields either won't appear in the data model, or you'll get a 404 Not Found HTTP error (if your product is listening to those fields).

Rush Hour history

When an event ends, the peak_period_start_time and peak_period_end_time values are cleared (and no longer available in the data model). Historical data for events is not available.

Resource use API

Before using this API, you must complete company verification and set up your product with Product data read/write permission.

See the API reference for more information on API call parameters.

Payload

The payload is the information you send to Nest when you pair a device or make a Resource use API call. It's JSON-formatted data that contains company identification and resource use data.

Resource use data is a set of values that represent some unit of measure and its corresponding timestamp. The units vary, depending on the resource:

  • electricity (joules)
  • gas (joules)
  • water (liters)

See payload examples for pairing and upload calls.

1. Pair the device

To use this API, your device must be paired with the structure using a REST call. This pairing request returns the device_id that you'll need to write your product data.

For the payload in this initial pairing call:

  • Include all resources used in your device
  • Do not include a device_id
curl -L -X POST -d '{
  "identification": {
    "serial_number": "SN 2AZQQ01AZ423545Z7"
  },
  "location": {
    "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw"
  },
  "software": {
    "version": "v8.0.1rc3"
  },
  "resource_use": {
    "electricity": {
      "value": 50.2,
      "measurement_reset_time": "2015-01-01T01:01:01.000Z",
      "measurement_time": "2015-01-01T01:02:35.000Z"
      }
    }
  }' \
"https://developer-api.nest.com/devices/ftl_lighting/lights?auth=c.VG6bfzyOxAltaih6P4v..."

The pairing request returns a 200 OK HTTP status code on success, along with the device_id for subsequent Resource use API write calls.

{
  "identification": {
    "device_id": "CPMEMSnC48JlSAHjQIp-kHI72IjLYHK_ul_c54UFb8CmPXNj4ixLbg",
    "serial_number": ...
    ...
        "measurement_time": "2015-01-01T01:02:35.000Z"
    }
}

2. Resource use API call

Send your product data to Nest with an API call that includes the device_id.

curl -L -X PUT -d '{
  "identification": {
      "device_id": "CPMEMSnC48JlSAHjQIpkHI72IjLYHK_ul_c54UFb8CmPXNj4ixLbg",
      "serial_number": "SN 2AZQQ01AZ423545Z7"
    },
    "location": {
      "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw",
      "where_id": "Fqp6wJI..."
      },
    "software": {
      "version": "v8.0.1rc3"
    },
    "resource_use": {
      "electricity": {
        "value": 50.2,
        "measurement_reset_time": "2015-01-01T01:01:01.000Z",
        "measurement_time": "2015-01-01T01:02:35.000Z"
      }
    }
  }' \
"https://developer-api.nest.com/devices/ftl_lighting_co/lighting/?auth=c.VG6bfzyOxAltaih6P4v..."

See Authenticating with OAuth 2.0 for more information on making REST calls.

See payload examples for help on constructing a payload for your product's specific usage.

3. Unpair the device

When you are done making API calls, unpair your device. This removes your product's association with the user's structure.

curl -L -X DELETE \
  "https://developer-api.nest.com/devices/ftl_lighting_co/lighting/?auth=c.VG6bfzyOxAltaih6P4v..."

The unpairing request returns a 200 OK HTTP status code on success.

Partial (non-atomic) writes

Atomic writes are not required, except in some cases. When you write product data, you can include any or all of the devices.

  • On a pairing call, the payload must include all resources in a device
  • On API calls, you can make a partial write at the node (object) level

For example, you can write to $company/$product_type/device_id/location, but not $company/$product_type/device_id/location/where_id

Data update frequency

Nest needs an accurate view of your product's usage while minimizing data transfer events. To do that, send data points only when the rate is changing. We can interpolate between those data points to get a complete view of your product's electricity, water, or gas use.

In these graphs, note how the frequency of the data points you choose to send can affect the accuracy of a user's Nest Home Report.

Data updates and update frequency

During times of high use, send more frequent updates. If no resources are being consumed (or it's a phase of constant use), updates are not needed.

Resource use data collection

Data is collected for monthly reporting. Each month begins at midnight (12AM) on the first day of the month and ends at 11:59PM on the last day of the month.

Nest account holders will see resource use data in their Home Report after the second full month of data collection for that product. You should expect your data to appear in a Home Report within 90 days.

Payload examples

Use these examples to build your payload for pairing and upload calls. Add or remove resources as necessary.

For example, you can also send only two resources in a payload.

Electricity
{
  "identification": {
    "device_id": "CPMEMSnC48JlSAHjQIp-kHI72IjLYHK_ul_c54UFb8CmPXNj4ixLbg",
    "serial_number": "SN 2AZQQ01AZ423545Z7"
  },
  "location": {
    "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw"
  },
  "software": {
    "version": "v8.0.1rc3"
  },
  "resource_use": {
    "electricity": {
      "value": 50.2,
      "measurement_reset_time": "2015-01-01T01:01:01.000Z",
      "measurement_time": "2015-01-01T01:02:35.000Z"
    }
  }
}
Gas
{
  "identification": {
    "device_id": "CPMEMSnC48JlSAHjQIp-kHI72IjLYHK_ul_c54UFb8CmPXNj4ixLbg",
    "serial_number": "SN 2AZQQ01AZ423545Z7"
  },
  "location": {
    "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw"
  },
  "software": {
    "version": "v8.0.1rc3"
  },
  "resource_use": {
    "gas": {
      "value": 42.7,
      "measurement_reset_time": "2015-01-01T01:01:01.000Z",
      "measurement_time": "2015-01-01T01:02:35.000Z"
    }
  }
}
Water
{
  "identification": {
    "device_id": "CPMEMSnC48JlSAHjQIp-kHI72IjLYHK_ul_c54UFb8CmPXNj4ixLbg",
    "serial_number": "SN 2AZQQ01AZ423545Z7"
  },
  "location": {
    "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw"
  },
  "software": {
    "version": "v8.0.1rc3"
  },
  "resource_use": {
    "water": {
      "value": 123.7,
      "measurement_reset_time": "2015-01-01T01:01:01.000Z",
      "measurement_time": "2015-01-01T01:02:35.000Z"
    }
  }
}
All
{
  "identification": {
    "device_id": "CPMEMSnC48JlSAHjQIp-kHI72IjLYHK_ul_c54UFb8CmPXNj4ixLbg",
    "serial_number": "SN 2AZQQ01AZ423545Z7"
  },
  "location": {
    "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw"
  },
  "software": {
    "version": "v8.0.1rc3"
  },
  "resource_use": {
    "electricity": {
      "value": 50.2,
      "measurement_reset_time": "2015-01-01T01:01:01.000Z",
      "measurement_time": "2015-01-01T01:02:35.000Z"
    },
    "gas": {
      "value": 42.7,
      "measurement_reset_time": "2015-01-01T01:01:01.000Z",
      "measurement_time": "2015-01-01T01:02:35.000Z"
    },
    "water": {
      "value": 123.7,
      "measurement_reset_time": "2015-01-01T01:01:01.000Z",
      "measurement_time": "2015-01-01T01:02:35.000Z"
    }
  }
}

Error messages

For information on what API call errors mean and how to handle them, see Error Messages.

Send feedback about...

Nest Developers
Nest Developers