API Definitions

Home Energy Scoring Tool API Definitions

The Home Energy Scoring Tool, or HEScore, API consists of all the software methods required to serve the Home Energy Scoring Tool (homeenergyscore.lbl.gov) and all third-party user interfaces in the Home Energy Score Program. These methods may be accessed via almost any Simple Object Access Protocol (SOAP)-compatible client found in popular languages, including PHP 5, JAVA, and .NET.

To use the HEScore API, you must be identified as a "Software Partner" by an HEScore administrator and have been assigned a developer’s API Key. Access will also be restricted to U.S. Department of Energy-approved Qualified Assessors. For information about the Qualified Assessor program, see the DOE Home Energy Score website.

Scoring Tool API Methods

Documentation of the methods used in the Scoring Tool v2017 API can be found on the API Methods page.

Scoring Tool API Web Services Description Languages

Sandbox - 2018WSDL URLWSDL Summary
 Sandbox WSDL URL WSDL Summary
ProductionWSDL URLWSDL Summary
  • Production: supports the assessment of residential homes by qualified assessors. DOE written authorization must be obtained before using the Production version of the WSDL, indicating that the DOE HEScore API Test Suite has been successfully passed and approved.
  • Sandbox: used by commercial providers to develop and test their third-party software against a copy of the 2017 production API.
  • Sandbox - 2018: contains a pre-release of new 2017 features, especially "breaking" features that require development by software providers to implement. DOE will notify software providers when the pre-release is ready for application by third-party developers.

Scoring Tool API Flow

This section describes the general steps for accessing the HEScore API and performing a complete Scoring Tool calculation. The method specifics, as well as sample code for each, can be found on the API Methods page.

  • To create a new building assessment case, call the submit_address method. Only the QA id and home address are submitted. This creates a building_id, which is provided in the API return. This building_id is used for the remaining steps. NOTE: The submitted home address must be independently verified by the API Licensee and Regional Partner and will be evaluated as part of the DOE's third-party graphical user interface (GUI) approval process.
  • To submit the home description, call the submit_inputs method. Inputs may be submitted in multiple partial sets, and the inputs may be revised until the results are committed.
  • After all of the required home description inputs have been submitted, call the calculate_base_building method to calculate the Base Home energy use. All submitted inputs are validated before any calculations are performed using a set of input validation rules. If any errors are found, they are returned, and the calculation is not initiated. This method can take up to 15 seconds to return. Thus, if you have a mobile application or an application that cannot reliably maintain a connection, submit the optional is_polling parameter. This will result in an immediate return, and the calculation status then can be checked using calculate_base_building_poll.
  • Upon a successful base home calculation, call the commit_results method to lock the Base Home inputs and mark them as being accurate by the Assessor. This allows the Base Home energy results and inputs to be used for home upgrade calculations.
  • To generate the automated Scoring Tool recommendations, call the calculate_package_building method. This analyzes a set of retrofit upgrades for the home that are screened against standardized costs, creates a package of the cost-effective upgrades, and calculates the package's energy use. This method can take up to 1 minute to return, so an optional is_polling parameter is provided as with calculate_base_building.
  • The final step is to call the generate_label method to generate PDF and PNG versions of the HEScore label.

Updates and Notifications:

February 14, 2017 - Release of version 2017 of the Home Energy Scoring Tool API. Some of the new features in this release include HVAC modeling of mini-split heat pumps and the inclusion of photovoltaic contributions to the overall energy score. HPXML v2.2 also is being supported, allowing XML-based entry of new modeling features.

March 22, 2015 - Release of version 2015 of the Home Energy Scoring Tool API. Some of the new features in this release include two types of foundations and roofs, modeling two HVAC systems, modeling wood heating, and additional assembly codes.

November 26, 2014 - The submit_hpxml_inputs method allowing submission of HPXML to the Home Energy Score is available on Sandbox for user testing.

May 18, 2014 - New polling options added to calculation methods and new polling methods added: calculate_base_building_poll and calculate_package_building_poll.

December 20, 2013 - Release of version 2014 of the Home Energy Scoring Tool API.

November 21, 2013 - The calculate XSD has been revised, combining the previously separate XSD's for calculate_base_building and calculate_package_building. This does not change the methods to be called and existing code should still work; the intent of this change is to eliminate redundancy and complication in the XSD.

October 25, 2013 - The API documentation is feature-complete. The API submit structure and returns are frozen until the new API is released into the Home Energy Score Program. Live calculated energy results are being served for both the base and upgraded building runs. Two new methods have been added to the documentation: retrieve_recommendations() and validate_inputs().

May 29, 2013 Q&A Webinar - During an informational webinar for Scoring Tool API Licensees, LBNL and DOE staff provided an overview of the Program and API in the new version of the Scoring Tool roll out. The slide deck is posted here.