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 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 with 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 submit and validate a building from an HPXML document:

• Call the submit_hpxml_inputs method to submit all inputs for a building. The inputs cannot be revised after submission.

• Call the validate_inputs method using the buliding_id from the submit_hpxml_inputs response. This method is not mandatory but is highly recommended. It provides errors that can be used for user feedback prior to requesting a time-consuming label generation.

  • 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.

• Once a building is submitted, 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.