Release History

The following is an ongoing log regarding the history of changes and updates to the Home Energy Scoring Tool. Major version changes to the scoring tool system are made annually, but continual bug fixes and improvements are released on a regular basis. Known issues not yet addressed are documented on the Known Issues page. The release history for the Home Energy Saver and Home Energy Saver Pro are documented here.


 DateRelease Type Description 
 January 2017v2017.3Planned (Major) This release is currently deployed to our Sandbeta server for testing.

Adds a new method to the API, upload_label. See that method's documentation for details.
 10/01/2017 v2017.2Major This release adds authentication to the API to prevent inappropriate access to data.

New methods: get_session_token and destroy_session_token. A call to get_session_token requires the user's qualified_assessor_id (user name) and password. The response contains a session_token field, which must be provided as a parameter for every other API method. Upon completion of a session, the destroy_session_token method can be triggered to invalidate the session token.

The session_token allows the API to permit and deny access to methods or results depending on the logged in user's permissions. Attempting to access methods or values that are not permitted results in a SOAP Fault response.

We have also taken this opportunity to clean up the API a bit by removing obsolete methods and fields.

Every method (except for get_session_token) now includes a mandatory session_token field. In addition, the following methods have been altered as documented:

  • archive_buildings_by_id, delete_buildings_by_id: 
    • qualified_assessor_id is removed. The user is determined from the session token.
    • The user must have the Assessor role and be the creator of the requested building (Note: This is not changed behavior but was hard-coded into the method previously and is now handled by the common access control layer).
  • calculate_base_building, calculate_package_building, commit_results
    • The fields validate_inputslog_type, and is_polling have been removed
    • Admin: All building IDs are permitted
    • Assessor: Only buildings assessed by the assessor are permitted
  • retrieve_extended_results, retrieve_inputs, retrieve_recommendations, retrieve_results, retrieve_label_results
    • The fields validate_inputslog_type, and is_polling have been removed
    • The values allowed to be in buildings or building_id are restricted based on the user's role(s)
      • Admin: All building IDs are permitted
      • Partner: Only buildings assessed by an assessor belonging to the Partner are permitted
      • Assessor: Only buildings assessed by the assessor are permitted
  • export_label_results
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Admin role to call this method
  • export_partner_label_results
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Partner role to call this method
  • generate_custom_label
    • The user must have the Admin role or must have the Assessor role and be the assessor that created both buildings
  • generate_label
    • is_polling is removed - this method already does not support asynchronous calls, so this has no impact on the method
    • The user must have the Admin role or must have the Assessor role and be the assessor that created the building
  • retrieve_buildings_by_id
    • If the user has the Admin role, no restrictions apply
    • Otherwise, if the user has the Assessor role, qualified_assessor_id must be set to the user's name
    • Users with only the Partner role may not use this method. They should use retrieve_buildings_by_partner instead
  • submit_address, submit_hpxml_inputs
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Assessor role
  • submit_inputs, validate_inputs
    • User must have the Assessor role and must be the user that created the building to be updated
  • retrieve_buildings_by_partner
    • partner is now optional
    • Admin: Must pass the partner field 
    • Partner: May not pass the partner field. Instead the method always returns results filtered for the currently logged-in partner.
  • These methods have been removed from the HEScore API
    • calculate_package_building_poll
    • calculate
    • doe2sim
    • doe2sim_multi
    • nearest_weather
    • retrieve_buildings_by_address (Use the address field of retrieve_buildings_by_id instead)
 02/14/2017 v2017.0Major HEScore API
  • Equipment efficiency input ranges have been updated to better reflect BPI 2400. Third-party software providing out-of-range values to the API will receive an error. New input ranges have been documented on the 2017 API Method Changes page.
  • Submit_inputs updated to allow identification of a mini-split heat pump and evaporative coolers as HVAC units. Also, updated to provide photovoltaic information that would contribute to the overall score.
  • Submit_hpxml_inputs updated to v2.2. This provides HPXML definitions for mini-split heat pumps, evaporative coolers, and photovoltaic.
HEScore GUI:
  • Updated "Format A" Label to include yearly average cost by kBtu/ft2 and ft2.
  • Rework View Summary screen to provide more validation.
HEScore Administration:
  • Created Partner dashboard to better manage Partner-Assessor information.
  • Provided a "Find an Assessor" function that allows Partners to manage a public list of Assessors. Includes a web link for homeowners to Find an Assessor that can be referenced from DOE websites.
 09/12/2016 v2015.9Incremental HEScore API:
  • Submit_Address updated to return an "Assessor has been blocked" error when the "Qualified_Assessor_Id" has been "Blocked" in the HEScore administrative database
  • Generate_Label updated to address a bug in the custom output of a Comparison Label. The "Currently Wastes," "Could Save," and "Could Eliminate" values have been updated to provide comparative values.
  08/17/2016 v2015.9MajorThis release unifies modeling and administration features into a coordinated web-based system. This includes expanding the Home Energy Score Administration Tool to better differentiate between Software Providers, Partners, Assessors, Admins, and QA activities. 

Software Provider’s Administrative Dashboard:

  • Local management of Software Provider API_Keys
  • Broadcast message to Provider POC

Partner’s Administrative Dashboard:

  • Partner/Assessor management interface
  • Partner-specific Custom Label Configuration

HEScore API and Graphical User Interface:

  • Updated Partner Data Export CSV results
  • Updated Administrative Data Export CSV results
  • Expanded find/filter/sort capability in Assessor’s Dashboard
  • Integration of Custom Label definitions to provide three (3) formats for HEScore Labels

Modeling API Updates:

  • There are no major updates to the modeling capability.
  • Updates to NREL’s HPXML input codes were verified and moved to production.
  • Model "Bug" fixes performed and tracked by LBNL were verified and moved to production.
  • Any changes to the API are backwards compatible, i.e., no changes were made to the API parameters; existing third-party software should run as-is.
  • The "Sandbeta" system was added to enable review and verification of new feature updates without compromising the existing FY15 training and production services.
 05/31/2016 v2015RIncremental
  • Modeling APIs provided by LBNL are being encapsulated, so future modeling bug fixes and features are quickly transferred, tested, and released.   
  • Extending the authorization portion of APIs to make it easier to manage Software Providers, HEScore Partners, and Assessors. This will allow the system to determine and convey access-related messages back to the Software Providers based on user’s role and the specific features and information that have access based on those roles.
  • HEScore Label Generation APIs and the HEScore Administration Tools are being expanded to provide multiple baseline template and Partner-customized labels. The Label Generation API call will have the same parameters, but it will use configuration parameters provided by the HEScore Partner and HEScore Administrator to apply label generation features. 
  • Unused API calls have been removed from the Sandbox WSDL. 
 05/10/2016 v2015 Incremental Unofficial labels are now watermarked “UNOFFICIAL” rather than “SAMPLE ONLY.”
 04/12/2016 v2015 Incremental Transferred LBNL update 110 to validate common walls in a townhouse.
 03/23/2016 v2015 Incremental Updated the Admin tool to allow access to "Resources," "Marketing Suite," and "HEScore Partner Communication & Engagement Packet."
 03/08/2016 v2015Incremental HEScore GUI to refine Better Building Label output
 02/02/2016 v2015Incremental HESAdmin Tool: Better differentiate Software Providers and HEScore Partners
HEScore GUI: Fixed Help documentation to properly describe water heater types
 01/13/2016 v2015 Incremental HEScore Partner and Admin data export update to the CSV file format with simplified header names 
 11/20/2015 v2015 Major Transition of HEScore from LBNL to PNNL