Getting Started with the Downloadable Runtime Report API

To use this API, one must first be an existing ecobee utility user. To enroll as a utility user, please visit https://www.ecobee.com/utilities/.

Introduction

The Downloadable Runtime Report API allows users to create and manage runtime report jobs. A runtime report job refers to a utility’s request for a generated runtime report. These reports are processed, encrypted, and uploaded to a publicly-available URL as ‘bundles’ in the order that the requests are received.

There are several advantages to using this API over the existing Runtime Report API. Calls using this API are now carried out asynchronously as users can ‘queue’ a runtime report job and check back on it’s status later. Additionally, the maximum number of thermostats to query is no longer capped at 25 per request. Finally, users can access up to 1 year of historical runtime report data as opposed to the 31 days allowed when using the previous version of our Runtime Report API.

Please note that uploaded bundles have a lifetime of 30 days before they expire. All accounts have a limit of how many jobs can be simultaneously queued at a time.

The following three API methods now exist for a utility user to create and manage their runtime report jobs:

Method Description
Create Runtime Report Job Creates a new runtime report job to be processed and returns the job id.
List Runtime Report Job Status Lists the status of any runtime report jobs and if complete, the URLs to access their generated report bundles.
Cancel Runtime Report Job Cancels a queued report job for the specified job id.

Report Job Statuses

After a request to create a report has been received, a queued runtime report job will be created. Please see the list below that describes each status:

Status Description
queued Indicates that the job has been received and is waiting to be processed.
processing Indicates that the job is now being processed.
completed Indicates that the job has been processed and uploaded successfully. Please refer to the 'files' field when carrying out the List Runtime Report Job Status call to download the requested runtime report bundles.
cancelled Indicates that the job has been cancelled.
error Indicates that the job has encountered an error while processing. Please refer to the 'message' field when carrying out the List Runtime Report Job Status call for an explanation of the error.

Creating an Account

In order to use any of the API methods above, a utility must first have a Runtime Report Account created for them.

After generating your PGP keys, send your public key to busidev@ecobee.com and keep your private key secret. Your bundle will be encrypted using your public key, and your private key allows you to decrypt and read it.

Both public key and private key can be generated by using the gpg command on Unix as seen below:

  • gpg --gen-key

After your keys have been generated, run the command below to display your public key:

  • gpg --armor --export

Copy the entire public key including the -----BEGIN PGP PUBLIC KEY BLOCK----- and -----END PGP PUBLIC KEY BLOCK----- lines and send it to busidev@ecobee.com.

One can also generate a gpg key pair by using OS-specific tools such as https://gpgtools.org/ (OSX) or https://www.gpg4win.org/ (Windows).

Once it has been confirmed that your account has been created, please refer to the POST Create Runtime Report Job page to create your first runtime report job.

File Naming Formats

Uploaded files have the following format: [JOB_ID]-[BUNDLE_NUMBER].tar.gz.gpg. Once decrypted and extracted, reports per thermostat identifier are represented as .csv files with the file name format [THERMOSTAT_IDENTIFIER]-[JOB_ID].csv.

Results may be bundled into multiple files if the number of thermostats in the request exceed a bundle's capacity. In this case, completed jobs will provide links to multiple file URLs.

As an example, if a utility user carried out a Create Runtime Report Job request for the thermostat identifier 123456789012, columns 'zoneCalendarEvent,zoneHvacMode,zoneHeatTemp,zoneCoolTemp,zoneAveTemp,dmOffset', and date range starting at '2017-13-04', a job with a randomly-generated id ('jobid1234' for example) will be created. A bundle named 'jobid1234-1.tar.gz.gpg' will then be created and uploaded to an S3 URL. This bundle will contain a single .csv file with the format '123456789012-jobid1234.csv'. When opened, its contents will look similar to the the following snippet:

date time zoneCalendarEvent zoneHVACmode zoneHeatTemp zoneCoolTemp zoneAveTemp dmOffset
2017-13-04 0:00:00 heatOff heatStage10n 69 60 64 0
2017-13-04 0:05:00 heatOff heatStage10n 69 60 64 0
2017-13-04 0:10:00 heatOff heatStage10n 69 60 64 0
.. .. .. .. .. .. .. ..

Bundle Decryption

Once a bundle has been downloaded, it must be decrypted. This can be done by using the gpg command on Unix as seen below (you will need to enter your passphrase defined when generated your PGP keys):

  • gpg --output yourBundle --decrypt yourBundle.tar.gz.gpg

Alternatively, users on OSX who installed GPGTools can follow the steps here to decrypt bundles. Windows users who installed GPG4Win can follow tutorials such as this.

Back To Top