Home Energy Scoring Tool API Definitions

The Home Energy Scoring Tool API consists of all the software methods needed 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 through almost any SOAP compatible client found in popular languages like PHP 5, JAVA and .NET.

In order to use the Home Energy Score API you must have previously obtained a 3scale client ID by completing the Licensing process. Access will also be restricted to U. S. DOE approved Qualified Assessors. For information on the Qualified Assessor program see the DOE Home Energy Score  website.

Scoring Tool API Methods

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

Scoring Tool API WSDL’s

• Note: U.S. Department of Energy written authorization must be obtained before using the Production version of the WSDL, indicating that DOE HEScore API Test Suite has been successfully passed and approved.

Scoring Tool API Flow

The general steps for accessing the API, and performing a complete Scoring Tool calculation are described below. The specifics of the methods as well as sample code for each can be found on the API Methods page

• Call the submit_address method to create a new building assessment case. 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 GUI approval process.
• Call the submit_inputs method to submit the home description. Inputs may be submitted in multiple partial sets and the inputs may be revised until the results are committed.
• After all the required home description inputs have been submitted, call the calculate_base_building method to calculate the Base Home energy use. All of 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 started. This method can take up to 15 seconds to return, so if you have a mobile application or an application that cannot reliably maintain a connection then submit the optional is_polling parameter. This will result in an immediate return and the status of the calculation can then 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 (either the automated Scoring Tool recommendations or the customized Regional Partner Other Report Options).
• 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 ones, and calculates the energy use of the package. 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 Home Energy Score label.

Updates and Notifications:

March 22, 2015 - Release of version 2015 of the Home Energy Scoring Tool API. Some of the new features in this release include: 2 types of foundations and roofs; modeling 2 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 caluclate_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 meeting Video is posted here (We apologize for technical difficulties cutting off the beginning.) The slide deck is posted here.