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. 

The Home page for our API's is developers.buildingsapi.lbl.gov. There are project specific pages for HES API, Home Energy Scoring Tool API, Energy IQ benchmarking tool, which include description of methods and sample code.
If you would like information on licensing, see the project licensing pages: HES API, Home Energy Scoring Tool API, or the Energy IQ API.

The HES API's are in active development and new versions of the API are planned with improved structure and data. Sub-pages to this article describe this re-architected API Object Model in detail. At present we have sections for the existing Multi-Family API,  2013 scoring tool beta, and a alpha version of a single family API.


What the Heck is an “API”?

LBNL’s Home Energy Saver project uses what are called “APIs” (or Application Programming Interfaces) 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.).