GET /api/v3/place/{placeId}/digest/savings/yearly

Retrieves rolled-up savings billing data for a single place on a yearly basis

GetPlaceSavingsYearlyV3 Permissions: BuildingsAndOrganizations (View)

Use this endpoint to get annual savings summaries for a specific place. For organizations, data is rolled up from all child places. Includes cost and use savings with commodity breakdown. For all places paginated, use GET /place/digest/savings/yearly instead.

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.

Path Parameters

Name	Description	Type	Required
placeId	Unique numeric identifier of the place to retrieve data for	integer (int32)	Required

Query Parameters

Name	Description	Type	Required
numberOfYears	Number of years to include (counting back from current year). Defaults to 4.	integer (int32)	Optional

Responses

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

Response Body Parameters

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": {      "unitCode": "string",      "unitId": 1,      "unitInfo": "string"
    },    "costUnit": {      "unitCode": "string",      "unitId": 1,      "unitInfo": "string"
    },    "results": [
      {      "batccCommonUse": 1.0,      "batccGlobalUse": 1.0,      "batccTotalCost": 1.0,      "commonUse": 1.0,      "globalUse": 1.0,      "savingsCommonUse": 1.0,      "savingsGlobalUse": 1.0,      "savingsTotalCost": 1.0,      "totalCost": 1.0,      "year": "string"
    }
    ]
  }
  ],  "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-06-29"
}

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