Portfolio Analytics

Endpoints

Creating Portfolio Analytics

Once you've created a portfolio with building(s) and added sufficient utility bills to each building, you're ready to generate portfolio analytics for that portfolio via the API.

Getting portfolio analytics data is a two part process:

1. Creating a new portfolio analytics object, including the buildings you want included.
2. Generating the portfolio analytics results, including results for each building included in the portfolio analytics.

Creating a New Portfolio Analytics

To create portfolio analytics, you must POST four pieces of information in JSON form to a particular portfolio's analytics endpoint, using that portfolios's ID (e.g. /api/v1/portfolios/23/analytics/).

The input JSON will look like this:

{
        "savings_target": "NOMINAL",
        "benchmark_data_type": "DEFAULT",
        "min_model_r_squared": 0.5,
        "building_ids": [1, 2, 3]
}

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

The benchmark_data_type property must be a value from the BenchmarkDataEnum. Currently, that means one of the following: DEFAULT or GENERATE

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

The building_ids property must be an array of integer building IDs. These buildings must be part of the current portfolio. If they're not, you can add them via the buildings API.

Building Subsets and the "All" Shortcut

Note that you don't have to include all buildings in the portfolio when creating a portfolio analytics. You can select just a subset for a particular portfolio analytics run.

If you do want all buildings from the portfolio, you can use the shortcut string "ALL" (instead of a list of integer IDs) to include all buildings in the current portfolio in this portfolio analytics.

The response from the server will return detailed information for the newly created portfolio analytics object. However, that object will not yet have generated results. We'll start the results generation in the next step.

 {
        "id": 19,
        "portfolio_id": 23,
        "savings_target": "NOMINAL",
        "benchmark_data_type": "DEFAULT",
        "min_model_r_squared": 0.6,
        ""portfolio_building_analytics": [
            {
                (portfolio building analytics object for each building)
            },
            ...
        ],
        "generation_result": "UNGENERATED",

        ...(other fields)...
}

Portfolio Analytics Results Calculation

After you have created a portfolio analytics, you can start the results generation process.

To do this, you call a special generate endpoint:

Given the example results from our last step, our generate endpoint would look like this:

If any errors occur the endpoint will return an error code and message. Otherwise, your portfolio analytics results generation task will now be underway!

At this point, you need to periodically 'poll' the portfolio analytics detail endpoint to find out what the generation status is.

Following our above example, the GET endpoint url would be

Continue to poll the portfolio analytics 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 will appear 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 Portfolio Analytics

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

/api/v1/portfolios/{portfolio ID}/analytics/{ analytics ID }/

For example, /api/v1/portfolio/18/analytics/29/

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

If the generation_result is IN_PROGRESS, you can continue to poll the endpoint (perhaps every 10 seconds) until the status changes to COMPLETE or FAILED

If the generation_result is UNGENERATED, the portfolio analytics have not been generated yet. See the "Updating Portfolio Analytics" section below for how to re-run portfolio analytics

If the generation_result is INVALIDATED, this means something has changed in the portfolio, or a building in that portfolio, in a way that invalidated the previously generated portfolio analytics results. See the "Updating Portfolio Analytics" section below for how to re-run portfolio analytics

Retrieving Portfolio Analytics Detail 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 by default. When format is set to html, BETTER returns the result in a self-contained HTML file.

When using HTML format, an additional ?show_building_links=true GET variable can be appended to the request to add hyperlinks to the building names shown in the "Buildings" table in the report.

Listing Portfolio Analytics

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

Updating Portfolio Analytics

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

Deleting a Portfolio Analytics

You can delete a portfolio analytics by sending a DELETE request to that particular portfolio analytics endpoint, using the parent portfolio's ID and the portfolio analytics ID (e.g. /api/v1/portfolios/18/analytics/29/). When you delete a portfolio analytics, any portfolio building analytics that belong to this portfolio analytics will be deleted.

Generating Net-Zero Information

If you want to generate net-zero information for a portfolio analytics run using PVWatts®, you must include the enable_pvwatts boolean variable in your request when first creating your portfolio analytics. When you generate the results, they will include net-zero information at both the building level and the portfolio level.

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

{
    "savings_target": "NOMINAL",
    "benchmark_data_type": "DEFAULT",
    "min_model_r_squared": 0.5,
    "enable_pvwatts": "true"
}