HES Pro/Consumer API

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. There is a project gallery on the developers.buildingsapi.lbl.gov site displaying 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 isdevelopers.buildingsapi.lbl.gov. This page provides a brief overview of the object model and the WSDL's for the Scoring Tool API for detailed descriptions of the methods see the developers.buildingsapi.lbl.gov site.

Note that in order to use the HES-SF API you must have previously obtained an API key by completing the Licensing process. This will be a 32 digit hexadecimal key.

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 retrieveal 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

Sandbox Session WSDL Calculate WSDL
Session WSDL Summary Calculate WSDL Summary
Production Session WSDL Calculate WSDL

An updated version of the API - the HES single family API - is under development. A first version of the single family API powers the current (now v2015) version of the Home Energy Score website, and the model will be expanded to accommodate the needs of the professional and consumer Home Energy Saver websites. See the "HES Pro API v2.0" pages on this site for early documentation of the new API structure.