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 create a customized application 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 hescore.labworks.org?

A: No - only if you want to create a new user interface for those tools.

Q: Who developed the HES API?

A: The Home Energy Saver API was developed by scientists at the Lawrence Berkeley National Laboratory, an internationally recognized center for research and development on energy efficiency. Authorization and access, label generation, and reporting have been updated and expanded by Pacific Northwest National Laboratory. The National Renewable Energy Laboratory assisted by conducting independent accuracy assessments. LBNL is a national laboratory of the U.S. Department of Energy.

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. Upcoming changes are regularly communicated to our developer community via e-mail, as well as on the Change Log page of this site.

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 API request 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. The Sandbox and Production environments run the same code at all times. You will see a performance difference, though, as we have more resources deployed on our production environment.

Q: Where do I report a bug or technical issue in the HES website or API?

A: HES.API.Support@pnnl.gov