Frequently Asked Questions

Q: What exactly are web services and APIs?
A: If the concepts are unfamiliar a reasonable place 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: 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: Yes. See the Project Gallery.

Q: Is the Home Energy Saver method 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?
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.

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 sytem. 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: What 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: Mail to: hes_api_support@lists.lbl.gov

Q: Do licensees get any tracking metrics on how their customers hit the service?
A: Not at this time.