GET /api/v3/meterGroup/{groupId}/digest/{dataView}/{chart}

Retrieves cost, use, unit cost or demand per day ranking data by meter group.

GetMeterGroupRankingV3 Permissions: GroupsAndBenchmarksModule (View)

Specify values for any query parameters whose database values are to be overridden.

PLEASE NOTE: As shown in the table below, this API endpoint returns different response types based on the “chart” value. Despite what you see below regarding HTTP status codes for each response type, all of these response types will return 200 OK.

Chart	Response Type
cost	MeterGroupDigestRankingResponseDTO
use	MeterGroupDigestRankingResponseDTO
unitCost	MeterGroupDigestRankingResponseDTO
demand	MeterGroupDigestDemandRankingResponseDTO

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
groupId	The meter group to retrieve data for	integer (int32)	Required
dataView	The desired data view - actual, calendarized, normalized	string	Required
chart	The desired chart - cost, use, unitcost, demand	string	Required

Query Parameters

Name	Description	Type	Required
billingPeriodOption	The billing period option - last12periods, lastyear, lastfiscalyear, custom (optional)	string	Optional
startPeriod	The custom start period (optional)	integer (int32)	Optional
endPeriod	The custom end period (optional)	integer (int32)	Optional
commodityId	Id of commodity to filter by (optional)	integer (int32)	Optional
commodityCategoryId	Id of commodity category to filter by (optional)	integer (int32)	Optional
highToLowRanking	Ranking from high to low, or low to high? (optional)	boolean	Optional
showExcludedMembers	Show group members excluded from the group? (optional)	boolean	Optional
showZeroAverages	Show group members whose ranking averages are zero? (optional)	boolean	Optional

Responses

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

Response Body Parameters

MeterGroupDigestRankingResponse

Property

Description

Type

averageCost

Average cost per day per benchmark factor across all members

number (double)

averageUnitCost

Average unit cost across all members

number (double)

averageUse

Average use per day per benchmark factor across all members

number (double)

averageValue

Average benchmark value across all members

number (double)

benchmarkFactorUnit

Display label for the benchmark factor unit (e.g., “sq ft”)

string

benchmarkUnit

Display label for the benchmark unit (e.g., “$/sq ft/day”)

string

benchmarkValueUnit

Display label for the benchmark value unit

string

costUnit

UnitChild

UnitChild properties

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

highCost

Highest cost per day per benchmark factor across all members

number (double)

highSavingsOpportunity

Highest savings opportunity amount across all members

number (double)

highUnitCost

Highest unit cost across all members

number (double)

highUse

Highest use per day per benchmark factor across all members

number (double)

highValue

Highest benchmark value across all members

number (double)

lowCost

Lowest cost per day per benchmark factor across all members

number (double)

lowUnitCost

Lowest unit cost across all members

number (double)

lowUse

Lowest use per day per benchmark factor across all members

number (double)

lowValue

Lowest benchmark value across all members

number (double)

medianCost

Median cost per day per benchmark factor across all members

number (double)

medianUnitCost

Median unit cost across all members

number (double)

medianUse

Median use per day per benchmark factor across all members

number (double)

medianValue

Median benchmark value across all members

number (double)

meterGroupCode

Short code for the meter group

string

meterGroupDisplay

User’s preferred display value for the group (code or info, based on system settings)

string

meterGroupId

Unique numeric identifier of the meter group

integer (int32)

meterGroupInfo

Descriptive name of the meter group

string

results

Per-member ranking results with cost, use, unitCost, and savings opportunity

MeterGroupDigestRankingChild[]

MeterGroupDigestRankingChild properties

Property

Description

Type

active

Indicates whether the Meter is Active

boolean

commodity

CommodityChild

CommodityChild properties

Property

Description

Type

commodityCode

The commodity code Required (defined)

string

commodityIcon

Icon

Icon properties

Property	Description	Type
code	The icon code Must be between 0 and 64 characters Required when Color is set	string
color	The icon color Must be between 0 and 32 characters Required when Code is set	string

commodityId

The commodity identifier Required (defined)

integer (int32)

commodityInfo

The commodity info Required (defined)

string

cost

Total cost for the meter over the selected period

number (double)

days

Number of billing days in the selected period for this meter

integer (int32)

includeInCharts

When true, this meter is included in group benchmark charts

boolean

isCalculatedMeter

Indicates whether the Meter is a calculated meter

boolean

isSplitChildMeter

Indicates whether the Meter is a child of a split

boolean

isSplitParentMeter

Indicates whether the Meter is a parent of a split

boolean

meterCode

Short code for the meter

string

meterDisplay

User’s preferred display value for the meter (code or info, based on system settings)

string

meterId

Unique numeric identifier of the meter

integer (int32)

meterInfo

Descriptive name of the meter

string

savingsOpportunity

Calculated savings opportunity if this meter performed at the group median

number (double)

unitCost

Unit cost (cost per unit of use) for the meter over the selected period

number (double)

use

Total use (consumption) for the meter over the selected period

number (double)

value

The benchmark value (cost/use/unitCost per day per benchmark factor) for ranking

number (double)

updated

The date and time the data was updated

string (date-time)

useUnit

UnitChild

UnitChild properties

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

Example Response application/json

{  "averageCost": 1.0,  "averageUnitCost": 1.0,  "averageUse": 1.0,  "averageValue": 1.0,  "benchmarkFactorUnit": "string",  "benchmarkUnit": "string",  "benchmarkValueUnit": "string",  "costUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "highCost": 1.0,  "highSavingsOpportunity": 1.0,  "highUnitCost": 1.0,  "highUse": 1.0,  "highValue": 1.0,  "lowCost": 1.0,  "lowUnitCost": 1.0,  "lowUse": 1.0,  "lowValue": 1.0,  "medianCost": 1.0,  "medianUnitCost": 1.0,  "medianUse": 1.0,  "medianValue": 1.0,  "meterGroupCode": "string",  "meterGroupDisplay": "string",  "meterGroupId": 1,  "meterGroupInfo": "string",  "results": [
    {    "active": false,    "commodity": {      "commodityCode": "string",      "commodityIcon": {},      "commodityId": 1,      "commodityInfo": "string"
    },    "cost": 1.0,    "days": 1,    "includeInCharts": false,    "isCalculatedMeter": false,    "isSplitChildMeter": false,    "isSplitParentMeter": false,    "meterCode": "string",    "meterDisplay": "string",    "meterId": 1,    "meterInfo": "string",    "savingsOpportunity": 1.0,    "unitCost": 1.0,    "use": 1.0,    "value": 1.0
  }
  ],  "updated": "2026-06-29",  "useUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  }
}

201 Created The resource was successfully created. The response body contains the new resource.

Response Body Parameters

MeterGroupDigestDemandRankingResponse

Property

Description

Type

averageCost

Average demand cost per day across all members

number (double)

averageValue

Average demand per day value across all members

number (double)

benchmarkFactorUnit

Display label for the benchmark factor unit

string

benchmarkUnit

Display label for the benchmark unit

string

benchmarkValueUnit

Display label for the benchmark value unit

string

costUnit

UnitChild

UnitChild properties

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

highCost

Highest demand cost per day across all members

number (double)

highValue

Highest demand per day value across all members

number (double)

lowCost

Lowest demand cost per day across all members

number (double)

lowValue

Lowest demand per day value across all members

number (double)

medianCost

Median demand cost per day across all members

number (double)

medianValue

Median demand per day value across all members

number (double)

meterGroupCode

Short code for the meter group

string

meterGroupDisplay

User’s preferred display value for the group (code or info, based on system settings)

string

meterGroupId

Unique numeric identifier of the meter group

integer (int32)

meterGroupInfo

Descriptive name of the meter group

string

results

Per-member demand ranking results

MeterGroupDigestDemandRankingChild[]

MeterGroupDigestDemandRankingChild properties

Property

Description

Type

active

Indicates whether the Meter is Active

boolean

commodity

CommodityChild

CommodityChild properties

Property

Description

Type

commodityCode

The commodity code Required (defined)

string

commodityIcon

Icon

Icon properties

Property	Description	Type
code	The icon code Must be between 0 and 64 characters Required when Color is set	string
color	The icon color Must be between 0 and 32 characters Required when Code is set	string

commodityId

The commodity identifier Required (defined)

integer (int32)

commodityInfo

The commodity info Required (defined)

string

cost

Total demand cost for the meter over the selected period

number (double)

includeInCharts

When true, this meter is included in group benchmark charts

boolean

isCalculatedMeter

Indicates whether the Meter is a calculated meter

boolean

isSplitChildMeter

Indicates whether the Meter is a child of a split

boolean

isSplitParentMeter

Indicates whether the Meter is a parent of a split

boolean

meterCode

Short code for the meter

string

meterDisplay

User’s preferred display value for the meter (code or info, based on system settings)

string

meterId

Unique numeric identifier of the meter

integer (int32)

meterInfo

Descriptive name of the meter

string

value

The demand per day value used for ranking

number (double)

updated

The date and time the data was updated

string (date-time)

Example Response application/json

{  "averageCost": 1.0,  "averageValue": 1.0,  "benchmarkFactorUnit": "string",  "benchmarkUnit": "string",  "benchmarkValueUnit": "string",  "costUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "highCost": 1.0,  "highValue": 1.0,  "lowCost": 1.0,  "lowValue": 1.0,  "medianCost": 1.0,  "medianValue": 1.0,  "meterGroupCode": "string",  "meterGroupDisplay": "string",  "meterGroupId": 1,  "meterGroupInfo": "string",  "results": [
    {    "active": false,    "commodity": {      "commodityCode": "string",      "commodityIcon": {},      "commodityId": 1,      "commodityInfo": "string"
    },    "cost": 1.0,    "includeInCharts": false,    "isCalculatedMeter": false,    "isSplitChildMeter": false,    "isSplitParentMeter": false,    "meterCode": "string",    "meterDisplay": "string",    "meterId": 1,    "meterInfo": "string",    "value": 1.0
  }
  ],  "updated": "2026-06-29"
}

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