Frequently Asked Questions

Q: What exactly are web services and APIs?
A: If the concepts are unfamiliar a reasonable placd to start might be Wikipedia. Here's how Wikipedia defines web services and APIs.

Q: Do I need to use these APIs if all I want to do is link to your site?
A: Definitely not. Just link. No strings attached. APIs are only needed if you want to customize the site for your users (e.g. ask fewer questions or change the user interface design).

Q: Do I need to sign a license in order to use hes.lbl.gov or hespro.lbl.gov or homeenergyscore.lbl.gov?
A: No - only if you want to create a new user interface for those tools.

Q: Who developed the HES APIs?
A: FIX? The Home Energy Saver APIs were developed by scientists at the Lawrence Berkeley National Laboratory, an internationally recognized center for research and development on energy efficiency. LBNL is a national laboratory of the U.S. Department of Energy. The team members are listed here.

Q: What are LBNL's goals of licensing technology and why does it charge some licensees?
A: Berkeley Lab licenses software and technologies to industry in order to move Lab inventions to the marketplace and benefit the public. Berkeley Lab seeks licensees that can marshal the requisite financial, R&D, manufacturing, marketing, and managerial capabilities and commitment to successfully commercialize Berkeley Lab innovations. Our goals are to:

  • Promote the use of Berkeley Lab technology to benefit society through licensing Lab inventions to companies capable of successfully commercializing them;
  • Support the research mission of the Lab through generating licensing income that supports future Lab research and by identifying industry partners to sponsor Lab research;
  • Earn a fair return and recognition for the Lab and inventors; and
  • Contribute to regional and national economic development.

In addition, indefinite government funding to offset the costs of maintaining the infrastructure to support licensees is not guaranteed, and usage-based payments help establish greater sustainability of the service.

Given license fees that are a tiny fraction of the millions of dollars we have invested in developing these web services, third-party software developers can avoid similar investments and get tremendous leverage by repurposing the tools we have developed.

Q: Do I need to also license DOE2.1E in order to use these APIs
A: No. DOE2.1E runs on our servers and thus you don't need to license it in order to run these APIs.

Q: Can I get an exclusive license?
A: No. LBNL provides non-exclusive licenses for HES to maximize the creative use of the APIs.

Q: How often will the APIs be updated?
A: We are in constant development, and plan for minor updates on a continuous basis as well as major updates several times a year.

Q: Do you have examples of how the APIs have been used?
A: FIX Yes. See the Project Gallery tab in this website.

Q: Is the Home Energy Saver BESTEST-certified?
A: No. The BESTEST process is not applicable to Home Energy Saver.

Q: Changes in internal loads resulting from changes in appliances/lights/misc/etc calculated outside of DOE-2 can affect the response of the thermal model and the HVAC equipment. Are these loads fed back into the HES model?
A: Yes. The internal loads for the DOE-2 run are based on the user inputs for all of the appliances, lighting, and miscellaneous equipment. The loads are split in to total daily lighting and total daily equipment and a fixed daily schedule is used to apportion them on an hourly basis.

Q: To what extent are individual schedules for appliances/lights/misc/etc exposed in the API. For the thermostat? Can we manipulate typical weekday/weekend schedules on an hourly basis? Can we manipulate individual days on an hourly basis?
A: Schedules for all appliances and lighting are fixed. The thermostat has a weekday/weekend schedule with 2 or 4 time periods per day, depending on type of thermostat specified.

Q: Can we expand the recommended upgrades?
A: No, currently the upgrade logic is fixed. We do have plans to add flexibility in the future.

Q: Can we test the impact of individual upgrades or run parametric studies through the API, or will this require us to make an APIrequest for each variant?
A: Yes, you would need to do a separate run. Though you can select and de-select measures and recalculate using the API.

Q: Can I use these APIs to replicate the Home Energy Scoring Tool functionality (http://hescore.labworks.org)?
A: Yes. However, third-party user interfaces expressly designed to replicate the Home Energy Scoring Tool (and thereby generate a Home Energy Score label) must be approved by the U.S. Department of Energy. There is no required approval for other uses of the HES APIs. More Info .

Q: Are there any functional differences between the sandbox environment and the production environment?
A: No functional differences. You will see a performance difference, as we have more resources deployed on our production environment.

Q: What's the difference between the base and version 1.1 APIs? I get more results from retrieveSessionUpgrades vs. retrieveSessionUpgrades11, though the documentation makes me think that I should use the 1.1 version of the APIs
A: The principle difference, currently, is how objects and data are passed through the system. The original version (v1) employed data arrays and was not WSDL compliant, while v1.1 employs SOAP and is WSDL compliant. In the not to distant future we will be disabling the v1 methods.

Q: How will the Home Energy Score results be included within the HES APIs?
A: The Home Energy Score results will be accessible via a specific set of new APIs which we are currently developing.

Q: Does retrieveSessionReports provide any formatting or is that up to the calling application? This is important to know how to generate the very specific report formats used by the Home Energy Score pilots.
A: The current plan is for Home Energy Score APIs to produce and deliver a certified label and report in PDF format.

Q: When using the APIs, will there be different results depending on whether I plan to use Home Energy Saver versus Home Energy Score functionality? Another way of putting that is do both applications use the same default values when building the home models?
A: The differences will be readily apparent when the Scoring Tool APIs come online. Basically all the inputs must be submitted to run the Scoring Tool APIs and produce a label. The standard HES APIs have a large variety of reports. View the tools online to see the structure and content of the reports. (For those without a password for homeenergyscore.lbl.gov, click on the homepage image to download a sample report.)

Q: What's function does retrieveUpgradesResult perform?
A: This retrieves the upgrade recommendations.

Q: What's the proper setup for the final parameter in?
A: This was not designed to be an exposed API and will be removed from the available options.

Q: Where do I report a bug or technical issue in the HES website?
A:FIX Mail to: hes_api_support@lists.lbl.gov

Q: Do licensees get any tracking metrics on how their customers hit the service?
A: Yes, licensees have direct access to usage stats.