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 any Simple Object Access Protocol (SOAP)-compatible client found in popular languages, including PHP, Java, and .NET. For our own internal development, which is in PHP, we use the native SoapClient class, and recommend its use to others.

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 API can be found on the API Methods page.

Scoring Tool API Web Services Description Languages

  • 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 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
  • There are two methods for creating and populating the values of a building:
    • Alternative 1:
      • Call the submit_address method to create a building. This method returns a building_id, which is used for the remaining steps.
      • To populate the home's values, 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. If you wish, you may also make use of the Home Energy Score Validation Engine, which is an open-source Node.js library available at https://github.com/hes-pnnl/hes-validation-engine.
    • Alternative 2:
      • Call the submit_hpxml method to both create and submit all inputs for a building. The inputs cannot be revised using this method.
  • Once a home is defined, call the generate_label method, which runs all home simulations and creates a PDF representation of the label.
  • For security reasons, when an assessor has completed her interaction with your application, it is advisable to call destroy_session_token.