Portfolio Building Analytics

Portfolio building analytics objects contain analytics information generated by BETTER for each building that was included in a portfolio analytics run.

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 API information please view the building analytics section

Endpoints

Buildings within Portfolio

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

Portfolio Building Analytics

Portfolio building analytics objects are immutable.

Portfolio building analytics are generated for each building during the portfolio analytics process. The data is almost exactly the same as a building analytics object. However, you cannot edit or delete portfolio building analytics items. You may only list them and view detail information. For that reason, BETTER distinguishes between these two almost identical building analytics output objects by using terminology "building analytics" and "portfolio building analytics."

Listing Portfolio Building Analytics

You can get a complete list of portfolio buildings analytics objects for a particular portfolio analytics by sending a GET request to the endpoint:

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

The API will return a list of portfolio building analytics detail objects.

Retrieve Portfolio Building Analytics

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

/api/v1/portfolios/{portfolio ID}/analytics/{portfolio analytics ID}/building_analytics/{portfolio building analytics ID}.

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

Retrieving Portfolio Building 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 ?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/portfolio/2/analytics/29/building_analytics/123?format=html&units=IP will serve the portfolio building analytics report in HTML format with values displayed in IP units.

Updating Portfolio Building Analytics

You cannot update (PATCH or PUT) existing portfolio building analytics.

Deleting Portfolio Building Analytics

You cannot delete an existing portfolio building analytics object. Only the parent portfolio analytics can be deleted (which will then delete all portfolio building analytics it contains).

Generating Net-Zero Information

If you want to generate net-zero information for a portfolio building analytics object using PVWatts®, you must include the enable_pvwatts boolean property in your request when generating the complete portfolio analytics: when a request to generate a portfolio analytics has the enable_pvwatts set to "true", BETTER will generate net-zero information for each building in the portfolio that has PVWatts® Calculator inputs defined.

NOTE: Just like other properties in the portfolio building analytics object, you cannot re-generate and modify net-zero information. You can only re-run the entire portfolio analytics after modifying a particular building's inputs.

For more information about how net-zero output is presented for each building in a portfolio analytics, please see the portfolio analytics API for details.