Building Analytics

Building analytics objects contain analytics information generated by BETTER for your stand-alone buildings.

NOTE: Building Analytics objects are associated with stand-alone buildings. Portfolio Building Analytics objects are associated with buildings included in a portfolio analytics run. For building analytics information generated as part of a portfolio analytics, please view the portfolio building analytics section

Endpoints

All Buildings

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

Creating Building Analytics

Once you've created a building and attached utility bills to it, you're ready to generate analytics for that building via the API.

Important: For single building analytics, the building's space type must be one of the following, where default benchmark statistics are available. See more details about the development of default benchmark statistics here.
Country Space Type
Unites States Office
K-12 School
Multifamily
Public Library
Mexico Office
Tunisia Hotel

To generate analytics, you must POST three pieces of information in JSON form to a particular building's analytics endpoint, using that building's ID (e.g. /api/v1/buildings/18/analytics/):

The input JSON will look like this:


{
        "savings_target": "NOMINAL",
        "min_model_r_squared": 0.6,
}
    

The savings_target property must be a value from the SavingsTargetEnum. Currently, that means one of the following: CONSERVATIVE, NOMINAL, or AGGRESSIVE

The min_model_r_squared property must be a number between 0 and 1 (inclusive).

The response from the server will return detail information for the generated building analytics. Each time you create analytics for a building, BETTER needs to start a background task to handle the computation. Since this process might awhile, the initial response will not include analytics data. Instead, you will see a generation_result field with a value IN_PROGRESS.



 {
        "id": 29,
        "building_id": 18,
        "savings_target": "NOMINAL",
        "benchmark_data_type": "DEFAULT",
        "min_model_r_squared": 0.6,
        "generation_result": "IN_PROGRESS",

        ...(other fields)...
}

    

At this point, you need to periodically 'poll' the building analytics detail endpoint to find out what the generation status is. If our example building's ID is 18, and the returned ID for the analytics we just generated was 29, this endpoint would look like /api/v1/buildings/18/analytics/29/

NOTE: You must periodically poll the API to find out the result of a building analytics generation.

Continue to poll the endpoint (perhaps every 10 seconds) until the generation_result field changes from IN_PROGRESS to another state.

If the analytics are successfully generated the generation_result field will change to a COMPLETE value, and the analytics information in the benchmark and assessment fields of the returned data.

If the analytics are not successfully generated, the generation_result field will change to a value of FAILED. The generation_message field will have a brief description of the error encountered when BETTER tried to generate the analytics.

Retrieve a Building Analytics

You can retrieve the properties of a particular building analytics run by sending a GET request to the endpoint for that building analytics, using the parent building's ID and the building analytics ID in the endpoint:

/api/v1/buildings/{building ID}/analytics/{analytics ID}/.

If the generation_result is COMPLETE, analytics data will appear in the analytics property and benchmark property.

Retrieving Building Analytics Output in HTML Format

For this particular endpoint, an optional GET variable ?format={type} can be appended to the endpoint to specify the type of content formatting you want. The format type can be json or html. The content will be served in JSON format if no suffix is provided. When format is set to html, BETTER returns the result in a self-contained HTML file.

When using HTML format, an additional ?units={type} GET variable can be appended to the endpoint to specify the units you want in the HTML report. The units type can be SI or IP. The content is served in SI units by default.

An Example...

For example, /api/v1/buildings/18/analytics/29/?format=html&units=IP will serve the building analytical report in HTML format with values displayed in IP units.

Listing Building Analytics

You can get a complete list of buildings analytics for a particular building by sending a GET request to the /api/v1/buildings/{building ID}/analytics/ endpoint. The API will return a list of building analytics details.

Updating Building Analytics

You cannot update (PATCH or PUT) existing building analytics. If you want to rerun an existing building analytics via the API, you must DELETE the existing Building Analytics and then POST create it again.

Deleting a Building Analytics

You can delete a building analytics by sending a DELETE request to that particular building analytics endpoint, using the parent building's ID and the building analytics ID (e.g. /api/v1/buildings/18/analytics/29/).

Generating Net-Zero Information

If you want to generate net-zero information for a building using PVWatts® calculator, you must include the enable_pvwatts boolean variable in your request when starting a building analytics calculation run.

IMPORTANT: You cannot enable PVWatts® calculator on a building analytics run when the building does not have PVWatts® Calculator inputs defined. See the buildings API docs for more details.

An example request that includes a request for net-zero information to be calculated using PVWatts®:


{
        "savings_target": "NOMINAL",
        "min_model_r_squared": 0.5,
        "enable_pvwatts": "true",
        "pvwatts_inputs": {
            ... any valid pvwatts input key and value...
        }
}

BETTER will attempt to contact the PVWatts® Calculator API during analytics generation. If it cannot, or if there is an error in receiving results, the net-zero portion of the building analytics will not be generated (and any available error information will be shown in its place).

Enabling PVWatts® Calculator will cause BETTER to contact the PVWatts® Calculator API (V8) service hosted by NREL in order to generate net-zero information from photovoltaics.

PVWatts® Calculator Inputs

When you make a POST request to start a building analytics run, you may provide one or more valid PVWatts® input values in the pvwatts_iputs object (see the "PVWatts® Calculator Inputs Values" table further below for details).

However, you may not provide a value for roof area. Roof area must be defined in your building.

For all other PVWatts® Calculator Inputs properties, if you do not provide a value, BETTER will find a default value to use in the following way:

  • BETTER will attempt to get that value from your building's pvwatts_inputs property.
  • If your building does not have that PVWatts® calculator input property defined, BETTER will get the default value for that property from your system settings.

But again, if you want to provide specific values for one or more of the PVWatts® calculator inputs for a building analytics run, you can do so in your POST request when you create a new building analytics, under the pvwatts_inputs key.

For example, you could provide specific values for the module type, system losses and the module tilt:


{
    "savings_target": "NOMINAL",
    "min_model_r_squared": 0.5,
    "enable_pvwatts": "true",
    "pvwatts_inputs": {
        "module_type": 0,
        "system_losses": -4.9,
        "tilt": 10
    }
}
    

The API schema provides the complete set of input values allowed in pvwatts_inputs.

These values are also listed below for your convenience.

PVWatts® Calculator Inputs Values
Property Description Value
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 based on the module_type value (see table below).

NOTE By default, BETTER determies module_efficiency by using the recommend values for typical module_types, as shown below. If a custom module_efficiency is provided, it will overwrite the default value for PV system capacity estimation. This option is primarily intended for advanced users who require more precise PV system capacity estimation.
Module Type Nominal Efficiency
0 (Standard) 19%
1 (Premium) 21%
2 (Thin Film) 18%

Type : Integer (percent)
Default : (See table)
Min value : 0
Max value : 25
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.45 means that when the modules are horizontal, 45% of the surface is occupied by the array.

NOTE Although this field can be set via the API, it is better not to define this field in your requests. When unspecified, BETTER will use the default value of 0.45.
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.

NOTE Although this field can be set via the API, it is better not to define this field in your requests. When unspecified, BETTER will use the default value of 1,000. This value is highly recommended for the module nameplate size estimation under the standard test conditions (STC).
Type : Float
Default : 1000
Min value : 200
Max value : 2000
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
bifaciality

The ratio of rear-side efficiency to front-side efficiency.

Type : Float
Default : 0.9
Min value : 0.0 Max value : 1
For more details, see NREL's PVWatts® API Docs.

PVWatts® Analytics

If a building analytics run finishes successfully, you will see a pvwatts_analytics object in the building analytics detail.

This object contains both the PVWatts® inputs and outputs properties, as well as error information.

Note that there is no pvwatts_inputs object in the building analytics detail: pvwatts_inputs is a write-only property used to get inputs into a building analytics run.


{
    "id": 29,
    "building_id": 18,
    "savings_target": "NOMINAL",
    "benchmark_data_type": "DEFAULT",
    "min_model_r_squared": 0.6,
    "generation_result": "COMPLETE",

    ... other values ..

    "pvwatts_analytics": {
        "roof_area": (value)
        "status":  (value),
        "module_type":  (value),
        "array_type":  (value),
        "module_efficiency":  (value),
        "system_losses":  (value),
        "tilt":   (value),
        "azimuth":  (value),
        "dc_to_ac_size_ratio":  (value),
        "inverter_efficiency":  (value),
        "ground_coverage_ratio":  (value),
        "dataset_type":  (value),
        "pvwatts_version":  (value),
        "station_info":  (value),
        "errors":  (value),
        "warnings":  (value),
        "outputs": {
            "ac_annual" : (value),
            "solrad_annual" : (value),
            "capacity_factor" : (value),
            "ac_monthly" : [...list of values...],
            "poa_monthly" : [...list of values...],
            "solrad_monthly" : [...list of values...],
            "dc_monthly" : [...list of values...],
        }
    }
}

PVWatts® Outputs

The outputs property in a pvwatts_analytics object contains output data generated by NREL's PVWatts® API. That object will have the following properties (descriptions provided by NREL's Output Fields documentation)

Property Description Value
ac_annual Annual AC system output. (kWhac) Type: Float
solrad_annual Annual solar radiation values. (kWh/m2/day) Type: Float
capacity_factor The ratio of the system's predicted electrical output in the first year of operation to the nameplate output, which is equivalent to the quantity of energy the system would generate if it operated at its nameplate capacity for every hour of the year. (AC-to-DC) Type: Float
ac_monthly Monthly AC system output. (kWhac) The array of values represents the value for each month, with the first element being for January and the last element being for December. Type: List of floats
poa_monthly Monthly plane of array irradiance values. (kWh/m2) The array of values represents the value for each month, with the first element being for January and the last element being for December. Type: List of floats
solrad_monthly Monthly solar radiation values. (kWh/m2/day) The array of values represents the value for each month, with the first element being for January and the last element being for December. Type: List of floats
dc_monthly Monthly DC array output. (kWhdc) The array of values represents the value for each month, with the first element being for January and the last element being for December. Type: List of floats