REST API for the BETTER Application

This page provides a brief overview on the BETTER API, including how to create and access buildings, building analytics, portfolios and portfolio analytics.

For detailed information on endpoints, allowed values, and so on, please view the interactive "API Schema" documentation page by clicking the button at right.

TLDR Guide to Using the API

To test the API from the command line:

  1. Create an API token:
    1. Sign Up to get a user account on this site.
    2. Request API access from the BETTER team. Send an email to support@better.lbl.gov and wait to hear back (shouldn't be long).
    3. Once you get API access from the BETTER team, come back to this site and log in. Once you are logged in, you should see your user name in the far right of the nav menu above. Click your user name to view the pulldown menu, and select "My Profile."
    4. Once the User Profile profile page is loaded, you will see a series of fields showing your profile information, including a field for your API token. This field will either already have a token (a long string of random characters) or it will have a note instructing you to click a button to generate your first token.
  2. Now that you have a token, you can make an HTTP request to a BETTER API endpoint. For quick tests you can use the command line program 'curl.' When you construct a request, make sure to include your token in the request header Authorization with a value of Token (your token). When setting this value, don't forget the space between "Token" and the token's random characters. (For more on setting headers in requests, see this article by Mozilla.)

For example, run the following command in a terminal on your machine to get a list of all buildings in JSON form:

        
curl -XGET https://better-lbnl.herokuapp.com/api/v1/buildings/ -H 'Authorization:Token (
            your user's API token )'
        
    

REST API for the BETTER Application

Purpose of the BETTER API

The BETTER REST-based API was created to allow you to programmatically create portfolios and buildings and then run analytics on them. The API will grow over time, but at first only limited features are available through a small set of endpoints. Each time we improve the API we'll update the API Schema docs to reflect those changes.

Features

The BETTER API operates as a simple REST-based api for creating, updating and deleting building and portfolios, and their related analytics.

Like most REST-based APIs, it supports the standard HTTP verbs (GET, POST, PATCH, DELETE) and uses json as the default data transport format.

Note that some endpoints also accept BuildingSync format. These docs will indicate support for that format where available.