Buildings

Endpoints

There are two main endpoints for working with buildings in BETTER. The first endpoint is the /api/v1/buildings/ endpoint. This endpoint allows you to list all buildings in your account. It also allows you to retrieve, update or delete any of those buildings, or create a new one.

Furthermore, any building you create will be part of a portfolio, so you can also access a building through its parent portfolio, as long as you first look up the portfolio's ID. If you have a portfolio with an ID of 5, you can list all the buildings in this portfolio at the endpoint /api/v1/portfolios/5/buildings/

Creating a Building

You can create a building by sending a POST request to the buildings endpoint. You must send in four pieces of information for BETTER to create a building. That information -- in JSON form in the body of the POST request -- should look like this:

{
    "name": "Some building name",
    "space_type": "OFFICE",
    "floor_area": 10000,
    "location": "Miami, Fl",
     "pvwatts_inputs": {
        "roof_area": 1000
        ... any other valid PVWattsInputs field ...
    }
}

See further below for how to create a building with extra information for net-zero calculations.

Building Currency

You can optionally provide a currency field with a three character value for the building's default currency. (Please see the OpenAPI documentation for allowed values.) You can only define a currency for a 'stand-alone' building. If your building is in a portfolio, it will always inherit the portfolio's currency.

For example:

{
    "name": "Some building name",
    "space_type": "OFFICE",
    "floor_area": 10000,
    "location": "Mexico City, Mexico",
    "currency": "MXN"
}

Note that if you do not provide a currency for a stand-alone building, BETTER will use the default currency defined in your user settings. If you haven't modified this value, it will be set to USD by default.

Listing Buildings

You can get a complete list of buildings by sending a GET request to the /api/v1/buildings/ endpoint. The returned information will include various properties for each building, including three arrays:

• analytics : a list of integer IDs for any building analytics generated for this building.
• utility_bills : a list of IDs for any utility bills assigned to this building.
• stations : a list of IDs for any stations assigned to this building as a 'neighbor' station.

To view more detail about the analytics and utility_bills for an individual building, you can use the "Retrieve" operation described below.

To list only the buildings in a single portfolio, use the /api/v1/portfolios/{portfolio ID}/buildings endpoint.

Retrieving a Building

You can retrieve a complete description of a building by sending a GET request to the endpoint for that building, using the building's ID.

For example, to retrieve the details of a building with ID of 18 would require sending a GET request to /api/v1/buildings/18/

The returned information will include a number of read-only fields for the building, including spatial information generated during geocoding.

The response will also include detailed information about each item in the utility_bills, stations, and analytics arrays for the building.

{
    "id": 9,
    "name": "My test building",
    "space_type": "OFFICE",
    "floor_area": 10000.0,
    "location": "San Francisco, CA",
    "zipcode": "94102",
    "state": "CA",
    "country": "US",
    "egrid_sub_region": "CAMX",
    "calendarized_utility_bills": null,
    "geo_lat": 37.77712,
    "geo_lng": -122.41964,
    "date_created": "2021-03-19T01:34:05.758529Z",
    "date_updated": "2021-03-24T00:40:38.596821Z",
    "analytics": [
        {
            "id": 200,
            "savings_target": "NOMINAL",
            "benchmark_data_type": "DEFAULT",
            "min_model_r_squared": 0.5,
            ... analytics information ...
        },
        {
            "id": 201,
            "savings_target": "NOMINAL",
            "benchmark_data_type": "DEFAULT",
            "min_model_r_squared": 0.6,
            ... analytics information ...
        }
    ],
    "utility_bills": [
        {
            "id": 400,
            ... utility bill information ...
        }
    ]
}

Editing a Building

You can edit a building by sending a PATCH request to the building endpoint, including the building's ID, in the same manner as the 'retrieve' process described above (.e.g /api/v1/buildings/18/).

You could update the building's name with a PATCH request like:

{
    "name": "My new building name"
}

If you want to replace all four pieces of information for a building, you should use a PUT request to the same endpoint.

Deleting a Building

You can delete a building by sending a DELETE request to that particular building's endpoint, using the building's ID (in the same way as retrieve or update, e.g. /api/v1/buildings/18/). When you delete a building, all related building analytics are also deleted. Furthermore, any portfolio analytics that include this building will also be set to an INVALIDATED state.

Adding a Building with Utility Bills (Shortcut)

Whenever you create a new building, you'll need to add a number of utility bills before BETTER can accurately fit a model to the building. Rather than creating the building first and then using the utility_bills endpoint to add utility bills one at a time, you can include utilities directly in a building when you create it.

{
    "name": "Some building name",
    "space_type": "OFFICE",
    "floor_area": 10000,
    "location": "Miami, Fl",
    "utility_bills": [
        {
            "fuel_type": "ELECTRIC_GRID",
            "bill_start_date": "2021-01-01",
            "bill_end_date": "2021-01-31",
            "consumption": 59961,
            "unit": "KWH"
        },
        {
            "fuel_type": "ELECTRIC_GRID",
            "bill_start_date": "2021-02-01",
            "bill_end_date": "2021-02-28",
            "consumption": 58891,
            "unit": "KWH"
        }
        ... more utility bills ...
    ]
}

This approach can save a lot of time when creating new buildings.

For more information on Utility access via the API, see the Utility Bills page in these docs

Generating Net-Zero Information

BETTER can generate net-zero information for a building using NREL's PVWatts® Calculator API (v8). However, to enable this feature, you must add extra information to your building so that BETTER can call NREL's PVWatts® Calculator API to calculate the energy production of grid-connected photovoltaics.

The values are contained in the pvwatts_inputs property when creating a building. At the very least, you must provide roof area information for your building if you want to add pvwatts_inputs properties to your building.

You can also set other PVWatts® Calculator inputs for a particular building. If you do not provide these values, BETTER will use your system settings to local default values to use for each PVWatts® Calculator input variable. ( You can change these values in system settings. )

For details on the properties of the pvwatts_inputs object, please see the API schema: /api/v1/docs/#/buildings/buildings_create

For example, one might post the following JSON to the building endpoint when creating a building with a floor area.

{
    "name": "Some building name",
    "space_type": "OFFICE",
    "floor_area": 10000,
    "location": "Miami, Fl",
    "pvwatts_inputs": {
        "floor_area": 1000
        ... any other valid PVWattsInputs field ...
    }
}

PVWatts® Values

Below is a table describing each property in the pvwatts_inputs object and the type of value it takes. It also shows the default the system uses if you provide no value (that is, if you haven't set that default to something else in system settings).

System Capacity

The PVWatts® Calculator V8 API also accepts a system_capacity property. The DC system capacity is the DC (direct current) power rating of the photovoltaic array in kilowatts (kW) at standard test conditions (STC).

In BETTER, this value is not entered by you, but rather calculated from a subset of the pvwatts_inputs properties. It is calculated with the following equation:

System Capacity (kW) = Usable Roof Area (m²) × Module Efficiency (%) × Ground Coverage Ratio × Solar Irradiance (W/m²) / 1000

Modify PVWatts® Calculator Inputs

If you want to modify PVWatts® Calculator inputs for a building, you can send a PATCH request to this url:

/api/v1/portfolios/{portfolio ID}/buildings/{ building ID}/pvwatts_inputs

The PATCH request can set new values for one or more PVWatts® input properties.

Delete PVWatts® Inputs

If you want to delete PVWatts® Calculator inputs for a building, you can send a DELETE request to this url: