Building Analytics

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

Endpoints

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.

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/

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

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.

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