About APIs

This page is a general introduction to the notion of an Application Programming Interface (API) and the the API's offered by the Home Energy Saver projects. 

Documentation of the HES API's is located at developers.buildingsapi.lbl.gov. There are project specific pages for the Single Family API and the Multifamily API, which include descriptions of methods and sample code. The Home Energy Scoring Tool API and documentation is hosted by PNNL here. 

If you would like information on licensing, there is a licensing page the covers the Single Family and the Multifamily APIs.

About API's

For those not familiar with the concept of an "API" the following brief overview may be helpful. API is an acronym for Application Programming Interface.  LBNL’s Home Energy Saver project uses APIs to power its own websites and to make its underlying data and calculations available to collaborators and other software developers on the web.

Looking at it from a high level, the system architecture is divided into layers.  At the base of the system (bottom of the diagram) is the data layer.  The data layer contains internal databases and external data services that allow the data to be tapped and used in calculations.

Sitting directly above the data layer is the application layer.  The application layer contains assorted libraries of software elements (“code libraries”) and is the heart of the system.  The “business logic”, i.e., the rules that govern how the system operates, reside in the code libraries in the application layer.  When people think about software, they are usually thinking about the code libraries in the application layer.  As you can see, this is just one part of the overall enterprise.

Sitting above the application layer is the service layer.  The service layer manages third-party interactions with the underlying software and data.  External systems interface with this system via web services, which are a type of application programming interface or API.  API licensees are given a unique key (or keys), which grants them access to web services and defines their usage rights once they have gotten into the system. Key-holders can use the entire system or pick and choose particular elements that are of interest. Any number of developers and websites can be created on top of a given API.

Websites created by third-party API licensees ultimately reside in the presentation layer, directly above the service layer.  This layer is referred to as the "presentation layer" because this is where the end-user interfaces (web sites) are developed and hosted by various third party providers.  It is worth noting that the existing Home Energy Saver project use this layer as well, making its web sites (HES, HESPro, and the Home Energy Scoring Tool) clients of the web service just like the API licensees.

And finally, sitting at the top of this structure, is the most important layer; the usage layer, which is populated by end users. The APIs allow developers to create user interfaces for any type of end-user device (desktop computer, smart-phone, etc.).