Old 2015 API Methods

HEScore Scoring Tool API Methods


These descriptions apply to the now deprecated 2015 version

The table contains links to the XSD description of the individual HEScore methods, as well as PHP code examples. 

XSD DocumentationDescriptionSample Code
submit_addressTakes an address and creates a default building.submit_address
submit_inputsSubmits or modifies a set of inputs for a building previously created with the submit_address() method. Note that all inputs do not need to be complete until the calculation step - one can submit and modify multiple times. The inputs may be unset by sending xsd:nil="true". The assembly codes for walls, roof, ceiling, windows and skylights are documented heresubmit_inputs
submit_hpxml_inputsCreates a new building from a set of building inputs created in HPXML (taking the place of both submit_address andsubmit_inputs) and returns a building_id. The HPXML must be converted to a Base 64 encoded payload.

NREL has documented the field mapping of HPXML to Home Energy Score inputs here. The Home Energy Scoring Tool does not validate the HPXML and if there are mapping problems (i.e. invalid enumerations, out of range values etc.) only a very general error will be returned, so the HPXML inputs should be done with care.

validate_inputsValidates that all inputs are correct using a set of input validation rules. Returns a status for each input that is either missing or not valid. If status is 2 the input is missing but is not required. Ifstatus is 1 the input is not valid and an error_message is also returned.validate_inputs
calculateThis XSD handles the calculation methods, the two calculation methods, which have similar submits, and the two polling methods. The calc_base_building() method does the energy calculation of the current submitted inputs for the building. The calc_package_building() method does the same for a "package" building that combines all of the recommended upgrades. The calc_package_building() method can only be run after the inputs are locked by running the commit_results() method. 
The calculation methods can take up to 1 minute to return. If you need a faster response you should set the optional is_pollingparameter to true. This will cause the called method to return immediately. You can then use subsequent calls to one of the two polling methods, calc_base_building_poll() and calc_package_building_poll(), to check the status of the building calculation (pending, success or error). These methods require only the user_key and building_id parameters.
commit_resultsFinalizes the model inputs configuration of a created building assessment. Upon a successful submit, the submitted building_id will be locked to prevent further changes to the model. (Note - There is no XSD for this method. Refer to the sample code for attibute information)commit_results
generate_labelInititates the label generation (PDF document) for a successfully calculated home scoring assessment.generate_label
retrieve_inputsReturns a list of the submitted inputs for an already created building assessment.retrieve_inputs
retrieve_label_resultsReturns a list of the Label results for a successfully calculated home scoring assessment.retrieve_label_results
retrieve_extended_resultsReturns an extended list of additional results in addition to the official Label results returned by retrieve_label_results().retrieve_extended_results
retrieveReturns the full set of Scoring Tool building energy calculation results.
retrieve_recommendationsReturns a list of the upgrade recommendations included in the package building as determined by calculate_package_building(). A list of all possible recommendations is available hereretrieve_recommendations
retrieve_buildings_by_idReturns a list of buildings for a specified Qualified Assessor (QA) number.retrieve_buildings_by_id
delete_buildings_by_idRemoves one or more specified buildings from the user's list of home assessments in the database.delete_buildings_by_id
archive_buildings_by_idTags one or more home assessments in the database as being archived.archive_buildings_by_id
retrieve_buildings_by_addressReturns the "Assessment Date" and the "Location" information for a specified address.retrieve_buildings_by_address

Changes from previous version

The production and sandbox APIs have been upgraded to v2015. For the convenience of developers transitioning from the v2014 to v2015 a summary table of the new functions and enumerations is available here.

Additional files

Because of the complexity of the wsdl, when using PHP the NuSOAP library is required. We are offering this build which has a patch implemented that corrects a bug that affects HEScore calls when using the regular NuSOAP distribution package.

transform.xsl is a small file that strips the name spaces from elements and attributes by only copying the local part of their names. If this is not present or not addressed correctly an error will be returned: "String could not be parsed as XML."