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/.
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:
|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:
|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.
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:
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