Home Energy Saver Pro/Consumer Sample Client Code

The HES-API consists of many methods designed to serve the HES websites found at hes.lbl.gov and hespro.lbl.gov. These methods may also be accessed through almost any SOAP compatible client found in popular languages like PHP, JAVA and .NET. We have setup a sandbox of our production system and sample SOAP client code to aid the use of the HES-API externally.

Some general user guidance

The version of the API this sample code represents has limited validation, something that will be improved upon in future releases. For the present users should exercise care that illogical settings are not made:

• Fuel type should be checked against heating equipment type (e.g. baseboard heaters should not be gas fueled).
• Duct locations should be checked against foundation type (e.g. don't put the ducts in the basement if the home is slab on grade).
• etc.

Something to particularly note is that there are variables that are handled differently in the Quick inputs than when using Detailed -- floorArea and Foundation or Floor Insulation:

Floor Area

• Quick uses floorArea to calculate dimension1 and dimension2
• Detailed does not use floorArea at all.

Foundation or Floor Insulation

• Quick uses foundationInsulationPresent to set the insulation level
• Detailed uses floorConstruction and foundationSideInsulationRValue.

In general, we urge API users to work with the Detailed inputs, rather than Quick.

The sample code specifies a fairly large set of inputs, partly to show the input table structure, but far from all that are available. It is not necessary to do all inputs in one pass, one can do multiple input passes and saves to one session, as in the HES GUI. Inputs that are not overwritten will be retained in the database, and inputs not specified are defaulted. This last is important to keep in mind if common end uses are intended to be excluded. To explore, start or save a session, then submit retrieveSessionById and examine the returned arrays. This also will display the input limits for many variables.

A fuller description of the available inputs can be obtained from our API_save_inputs workbook. Also check the HES Engineering Documentation, for methods, data sources and known issues.

Because HES defaults many inputs the API user will need to be aware of explicitly removing end uses not to be modeled, set the number to zero rather than just not including. Again, the API save inputs workbook will be an important source for this.

Code Samples

PHP 5 newSession sample code

The JAVA sample - for steps to get the sample code go here.

The C# .NET sample - for steps to get the sample code go here.