Buildings

Endpoints

All Buildings

Detail:
/api/v1/buildings/{ building ID}

Buildings within Portfolio

List:
/api/v1/portfolios/{ portfolio ID}/buildings/
Detail:
/api/v1/portfolios/{portfolio ID}/buildings/{ building ID}

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/

NOTE: Every building in BETTER is placed in a portfolio. When you sign up with BETTER, behind the scenes we create a 'DEFAULT' portfolio for your account. So anytime you add a building directly to BETTER via the /api/v1/buildings/ endpoint, we place that building in your DEFAULT portfolio. You can safely ignore this fact and just treat these buildings as stand-alone.

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": {
        "floor_area": 1000
        ... any other valid PVWattsInputs field ...
    }
}

The name property can be a unicode string up to 200 characters in length.

The space_type property must be one of a limited set of values...see the SpaceTypeEnum definitions in the API docs for a complete list of values you can use.

The floor_area is the floor area in square meters.

The location property is the city and state of the building. We will use this information to gecode the building and find the nearest weather station for historical weather data.

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

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": "DEFAULT",
            "min_model_r_squared": 0.5,
            ... analytics information ...
        },
        {
            "id": 201,
            "savings_target": "NOMINAL",
            "benchmark_data": "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.

IMPORTANT NOTE:
If you update a building's floor area, space type or location, you will invalidate all building analytics that belong to this building, as well as any portfolio analytics that include this building. The affected analytics will be set to an INVALIDATED state. "INVALIDATED" simply means previously generated analytics results have been removed because underlying data has changed -- you need to rerun the analytics to generate new, good results. See below for how to rerun analytics for buildings.

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 (v6). 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

NOTE: Floor area is always in square meters.

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).

PVWatts® Calculator Inputs Values
Property Description Value
roof_area

The available roof area for PV array installation. This input is used to calculate the system size.

Type : Float
Default : ( No default )
Min value : 1.0
array_type

The array type describes whether the PV modules in the array are fixed, or whether they move to track the movement of the sun across the sky with one or two axes of rotation. The default value is for a fixed array, or one with no tracking.

Type : Integer
Values:
  • 0: Fixed open rack
  • 1: Fixed roof mounted
  • 2: Axis 1
  • 3: Axis 1 backtracking
  • 4: Axis 2
Default : 1
module_type

The module type describes the photovoltaic modules in the array. If you do not have information about the modules in the system, use the default Standard module type.

Type : Integer
Values:
  • 0: Standard
  • 1: Premium
  • 2: Thin Film
Default : 0
module_efficiency

The solar to electricity conversion efficiency of the PV modules. The default value is 16%.

Type : Integer (percent)
Default : 16
Min value : 0
Max value : 100
system_losses

The system losses account for performance losses you would expect in a real system that are not explicitly calculated by the PVWatts® model equations.

Type : Float
Default : 12
Min value : 0.0
Max value : 90.0
tilt

The tilt angle is the angle from horizontal of the photovoltaic modules in the array. For a fixed array, the tilt angle is the angle from horizontal of the array where 0° = horizontal, and 90° = vertical. For arrays with one-axis tracking, the tilt angle is the angle from horizontal of the tracking axis. The tilt angle does not apply to arrays with two-axis tracking.

Type : Float
Default : 20
Min value :
azimuth

For a fixed array, the azimuth angle is the angle clockwise from true north describing the direction that the array faces. An azimuth angle of 180° is for a south-facing array, and an azimuth angle of zero degrees is for a north-facing array. For an array with one-axis tracking, the azimuth angle is the angle clockwise from true north of the axis of rotation. The azimuth angle does not apply to arrays with two-axis tracking. The default value is an azimuth angle of 180° (south-facing) for locations in the northern hemisphere and 0° (north-facing) for locations in the southern hemisphere.

Type : Float
Default : 180
Min value : 0
Max value : 359.999
dc_to_ac_size_ratio

The DC to AC size ratio is the ratio of the array's DC rated size to the inverter's AC rated size.

Type : Float
Default : 1.2
Min value : greater than 0
inverter_efficiency

The inverter's nominal rated DC-to-AC conversion efficiency, defined as the inverter's rated AC power output divided by its rated DC power output. The default value is 96%.

Type : Float
Default : 96
Min value : 90
Max value : 99.5
ground_coverage_ratio

The ground coverage ratio (GCR) is the ratio of module surface area to the area of the ground or roof occupied by the array. A GCR of 0.5 means that when the modules are horizontal, half of the surface below the array is occupied by the array. The default value is 0.4, and typical values range from 0.3 to 0.6.

Type : Float
Default : 0.4
Min value : 0
Max value : 3.0
solar_irradiance

The power per unit area (surface power density) received from the Sun in the form of electromagnetic radiation in the wavelength range of the measuring instrument. The default value is 1 kW/m²

Type : Float
Default : 1000
Min value : 0.0 Max value : 10000
dataset_type

The weather dataset PVWatts® uses.

Type : Character
Values:
  • nsrdb: Fixed open rack
  • tmy2: Fixed roof mounted
  • tmy3: Axis 1
  • intl: Axis 1 backtracking
Default : tmy2
For more details, see NREL's PVWatts® API Docs.

System Capacity

The PVWatts® Calculator V6 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 (kW/m²)


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:

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