GET /api/v3/place/digest/savings/yearly

Retrieves rolled up savings billing data by building/organization for a given number of years- Result includes cost, use, unit cost on an yearly basis. It also includes a commodity level break up.

GetPlaceSavingsYearlyListV3 Permissions: BuildingsAndOrganizations (View)

Paginated endpoint — This API returns paginated results. Use the pageNumber and pageSize query parameters to control which page of results is returned. The response includes pagination metadata in the response headers. See the Pagination guide for details.

Request Headers

Header	Value	Required	Description
ECI-ApiKey	string	Yes	Your API key. See Authentication.
Content-Type	application/json	Yes	All requests must specify JSON content type.

Query Parameters

Name	Description	Type	Required
numberOfYears	Number of years of data to return includes the current year - Defaults to 4	integer (int32)	Optional
pageSize	The number of elements to return in a page	integer (int32)	Optional
pageNumber	The current page number	integer (int32)	Optional

Response Headers

This endpoint returns pagination metadata in the response headers.

Header	Type	Description
PageNumber	integer	The current page number (1-based).
PageSize	integer	The maximum number of items per page.
TotalNumberOfRecords	integer	The total number of records matching the query across all pages.
TotalPages	integer	The total number of pages. Increment pageNumber until it equals this value to retrieve all results.

See the Pagination guide for iteration examples and best practices.

Responses

200 OK The request succeeded and the response body contains the requested data.

Response Body Parameters

Array of:

PlaceDigestSavingsYearlyResponse

Property

Description

Type

allTimeBATCCGlobalUse

Program to Date BATCC (Baseline Adjusted to Current Conditions) Global Use

number (double)

allTimeBATCCTotalCost

Program to Date BATCC (Baseline Adjusted to Current Conditions) Total Cost

number (double)

allTimeGlobalUse

Program to Date Global Use

number (double)

allTimeSavingsGlobalUse

Program to Date Savings Global Use = allTimeBATCCGlobalUse - allTimeGlobalUse

number (double)

allTimeSavingsTotalCost

Program to Date Savings Total Cost = allTimeBATCCTotalCost - allTimeTotalCost

number (double)

allTimeTotalCost

Program to Date Savings Total Cost

number (double)

commodities

An array of savings yearly data per commodity

PlaceDigestSavingsYearlyResponse+CommodityData[]

PlaceDigestSavingsYearlyResponse+CommodityData properties

Property

Description

Type

allTimeBATCCCommonUse

Program to Date BATCC (Baseline Adjusted to Current Conditions) Common Use

number (double)

allTimeBATCCGlobalUse

Program to Date BATCC (Baseline Adjusted to Current Conditions) Global Use

number (double)

allTimeBATCCTotalCost

Program to Date BATCC (Baseline Adjusted to Current Conditions) Total Cost

number (double)

allTimeCommonUse

Program to Date Common Use

number (double)

allTimeGlobalUse

Program to Date Global Use

number (double)

allTimeSavingsCommonUse

Program to Date Savings Common Use = allTimeBATCCCommonUse - allTimeCommonUse

number (double)

allTimeSavingsGlobalUse

Program to Date Savings Global Use = allTimeBATCCGlobalUse - allTimeGlobalUse

number (double)

allTimeSavingsTotalCost

Program to Date Savings Total Cost = allTimeBATCCTotalCost - allTimeTotalCost

number (double)

allTimeTotalCost

Program to Date Total Cost

number (double)

commodityCode

The commodity code

string

commodityId

The commodity identifier

integer (int32)

commodityInfo

The commodity info

string

commonUseUnit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

costUnit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

results

An array of yearly data

PlaceDigestSavingsYearlyResponse+CommodityData+CommodityResults[]

PlaceDigestSavingsYearlyResponse+CommodityData+CommodityResults properties

Property	Description	Type
batccCommonUse	BATCC (Baseline Adjusted to Current Conditions) Common Use	number (double)
batccGlobalUse	BATCC (Baseline Adjusted to Current Conditions) Global Use	number (double)
batccTotalCost	BATCC (Baseline Adjusted to Current Conditions) Total Cost	number (double)
commonUse	Common Use	number (double)
globalUse	GlobalUse	number (double)
savingsCommonUse	Savings Common Use = BATCCCommonUse - CommonUse	number (double)
savingsGlobalUse	Savings Global Use = BATCCGlobalUse - GlobalUse	number (double)
savingsTotalCost	Savings Total Cost = BATCCTotalCost - TotalCost	number (double)
totalCost	Total Cost	number (double)
year	Year	string

costUnit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

globalUseUnit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

placeCode

The place code

string

placeId

The place identifier

integer (int32)

placeInfo

The place info

string

results

An array of savings yearly data

PlaceDigestSavingsYearlyResponse+Results[]

PlaceDigestSavingsYearlyResponse+Results properties

Property	Description	Type
batccGlobalUse	BATCC (Baseline Adjusted to Current Conditions) Global Use	number (double)
batccTotalCost	BATCC (Baseline Adjusted to Current Conditions) Total Cost	number (double)
globalUse	GlobalUse	number (double)
savingsGlobalUse	Savings Global Use = BATCCGlobalUse - GlobalUse	number (double)
savingsTotalCost	Savings Total Cost = BATCCTotalCost - TotalCost	number (double)
totalCost	Total Cost	number (double)
year	Year	string

updated

The date and time the data was updated

string (date-time)

Example Response application/json

[
  {    "allTimeBATCCGlobalUse": 1.0,    "allTimeBATCCTotalCost": 1.0,    "allTimeGlobalUse": 1.0,    "allTimeSavingsGlobalUse": 1.0,    "allTimeSavingsTotalCost": 1.0,    "allTimeTotalCost": 1.0,    "commodities": [
      {      "allTimeBATCCCommonUse": 1.0,      "allTimeBATCCGlobalUse": 1.0,      "allTimeBATCCTotalCost": 1.0,      "allTimeCommonUse": 1.0,      "allTimeGlobalUse": 1.0,      "allTimeSavingsCommonUse": 1.0,      "allTimeSavingsGlobalUse": 1.0,      "allTimeSavingsTotalCost": 1.0,      "allTimeTotalCost": 1.0,      "commodityCode": "string",      "commodityId": 1,      "commodityInfo": "string",      "commonUseUnit": {},      "costUnit": {},      "results": []
    }
    ],    "costUnit": {      "unitCode": "string",      "unitId": 1,      "unitInfo": "string"
    },    "globalUseUnit": {      "unitCode": "string",      "unitId": 1,      "unitInfo": "string"
    },    "placeCode": "string",    "placeId": 1,    "placeInfo": "string",    "results": [
      {      "batccGlobalUse": 1.0,      "batccTotalCost": 1.0,      "globalUse": 1.0,      "savingsGlobalUse": 1.0,      "savingsTotalCost": 1.0,      "totalCost": 1.0,      "year": "string"
    }
    ],    "updated": "2026-03-30"
  }
]

204 No Content The request succeeded. No content is returned in the response body.