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. This Runtime Report account is created using PGP public key that is generated by the utility.

The utility must generate PGP keys and submit a ticket to the ecobee Developer Relations team via the Help Center. Once setup, the reports will be encrypted using your public key, and your private key will allow 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 Utility Help Desk.

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