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

SandbetaWSDL URL
 Sandbox WSDL URL
ProductionWSDL URL
  • 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.
  • Sandbeta: contains a pre-release version new features. We use this server to host new features that will break backwards compatibility to provide software providers an environment against which they can program their own updates. DOE will notify software providers when such a pre-release version has been made available for development 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 can be found on the API Methods page.

  • To authenticate yourself to the API, you must first call get_session_token by passing the assessor's user name and password. The returned session_key must be included in all other calls to the API.
  • To create a new building assessment case, call the submit_address method. Only the QA id and home address are submitted. This method returns a building_id, which 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 submit_inputs. Inputs may be submitted in multiple partial sets, and the inputs may be revised until the results are committed.
  • To validate the home description, you may call validate_inputs. This method is not mandatory but provides a way to get errors for user display before a building calculation is requested.
  • 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.
  • 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.
  • 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.
  • The final step is to call the generate_label method, which creates a PDF representation of the label and returns a set of URLs for that PDF file, as well as for single-page PNG images rendered from the PDF.
  • For security reasons, when an assessor has completed her interaction with your application, it is advisable to call destroy_session_token.
Subpages (3): API Methods Change Log FAQs