The Home Energy Saver API enables software developers to access the calculation engine of the Home Energy Saver, the first web-base home energy calculator. The HES API can be used to build applications that support home inspections or comprehensive energy assessment. Our project gallery displays the work of third party developers using the HES API. The Home Energy Saver API also powers the existing (or Legacy) Home Energy Saver professional and consumer websites.
The main Home Energy Saver API documentation site is developers.buildingsapi.lbl.gov. This page provides a brief overview of the object model and the WSDL's for the Scoring Tool API.
Note that in order to use the HES-SF API you must have previously obtained an API key by completing the Licensing process.
The general steps for accessing the API, and performing a calculation are as follows:
Call the newSession method in the api to create a new session.The newSession method returns pages of results that are designed for a website to parse and build forms. The only data required to start a session is a Zip Code
Retrieve the session_id from the newSession results. The sample code shows you how to just retrieve the session_id which is all that is needed to move forward.
Customize the modeled home using saveSession11 method. Most often this will be done by initiating a SOAP client object using the WSDL that is published for the API, and using that SOAP object to submit the three input arrays (saveInputs, lightInputs, and extraInputs) that describe the home configuration. saveSession can also initiate the energy and cost calculation using the "validate" parameter.
Once the session has been saved and calculated, you may retrieve the results of the calculation. There are several specialized retrieve methods, allowing retrieval of results for the whole house or by several end uses.
In addition to customizing the home configuration HES allows for customization of the specific upgrades to be applied.
HES-Pro/Consumer API Object Model
HES-Pro/Consumer API WSDL's
An updated version of the API - the HES single family API - is under development. A first version of the single family API powers the Home Energy Score, and the model will be expanded to accommodate the needs of the professional and consumer Home Energy Saver websites.