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

Retrieves ranking data by place group.

GetPlaceGroupRankingV3 Permissions: GroupsAndBenchmarksModule (View)

Depending on the “chart” parameter retrieved ranking data could be cost, use, or demand per area, cost or use per day, heating sensitivity or cooling sensitivity Specify values for any query parameters whose database values are to be overridden. For the heating sensitivity and cooling sensitivity charts we sort by weather sensitivity (slope) and exclude non-weather meters

PLEASE NOTE: As shown in the table above, 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
areaCost PlaceGroupDigestAreaRankingResponseDTO
areaUse PlaceGroupDigestAreaRankingResponseDTO
cost PlaceGroupDigestRankingResponseDTO
use PlaceGroupDigestRankingResponseDTO
areaDemand PlaceGroupDigestAreaDemandRankingResponseDTO
coolingSensitivity PlaceGroupDigestWeatherRankingResponseDTO
heatingSensitivity PlaceGroupDigestWeatherRankingResponseDTO
benchmark1Use PlaceGroupDigestBenchmarkRankingResponseDTO
benchmark2Use PlaceGroupDigestBenchmarkRankingResponseDTO
benchmark3Use PlaceGroupDigestBenchmarkRankingResponseDTO
benchmark1Cost PlaceGroupDigestBenchmarkRankingResponseDTO
benchmark2Cost PlaceGroupDigestBenchmarkRankingResponseDTO
benchmark3Cost PlaceGroupDigestBenchmarkRankingResponseDTO

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 place group to retrieve data for integer (int32) Required
dataView The desired data view - actual, calendarized, normalized string Required
chart The desired chart - areacost, areause, areademand, cost, use, heatingsensitivity, coolingsensitivity, benchmark1use, benchmark1cost, benchmark2use, benchmark2cost, benchmark3use, benchmark3cost string Required

Query Parameters

Name Description Type Required
billingPeriodOption The billing period option - last12periods, currentyear, 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

PlaceGroupDigestAreaDemandRankingResponse
Property Description Type
averageCost Average cost for this group number (double)
averageUse Average use for this group number (double)
benchmarkFactorUnit This will provide the unit for the benchmarking factor eg:ft² or day string
benchmarkUnit This will provide the benchmark unit eg:MMBTU/ft² or $/day string
benchmarkValueUnit This will provide the unit for the benchmark value eg:$ for cost/day, MMBTU for annualized use/area string
costUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
highArea Highest area for this group number (double)
highCost Highest cost for this group number (double)
highSavingsOpportunity The highest savings opportunity for this group number (double)
highUse Highest use for this group number (double)
highValue Highest benchmark value for this group number (double)
lowArea Lowest area for this group number (double)
lowCost Lowest cost for this group number (double)
lowUse Lowest use for this group number (double)
lowValue Lowest benchmark value for this group number (double)
medianArea Median area for this group number (double)
medianCost Median cost for this group number (double)
medianUse Median use for this group number (double)
medianValue Median benchmark value for this group number (double)
placeGroupCode string
placeGroupDisplay This is the user’s preferred way of viewing this entity - could be code or info based on the master “data object view” setting in DB string
placeGroupId integer (int32)
placeGroupInfo string
results PlaceGroupDigestAreaRankingChild[]
PlaceGroupDigestAreaRankingChild properties
Property Description Type
area The area for this place integer (int32)
cost The cost for this place number (double)
includeInCharts boolean
incompleteData Does this place have incomplete data? boolean
placeCode string
placeDisplay string
placeId integer (int32)
placeInfo string
savingsOpportunity The savings opportunity for this place number (double)
use The use for this place number (double)
value The benchmark value for this place number (double)
totalArea Total area for this group 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,  "averageUse": 1.0,  "benchmarkFactorUnit": "string",  "benchmarkUnit": "string",  "benchmarkValueUnit": "string",  "costUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "highArea": 1.0,  "highCost": 1.0,  "highSavingsOpportunity": 1.0,  "highUse": 1.0,  "highValue": 1.0,  "lowArea": 1.0,  "lowCost": 1.0,  "lowUse": 1.0,  "lowValue": 1.0,  "medianArea": 1.0,  "medianCost": 1.0,  "medianUse": 1.0,  "medianValue": 1.0,  "placeGroupCode": "string",  "placeGroupDisplay": "string",  "placeGroupId": 1,  "placeGroupInfo": "string",  "results": [
    {    "area": 1,    "cost": 1.0,    "includeInCharts": false,    "incompleteData": false,    "placeCode": "string",    "placeDisplay": "string",    "placeId": 1,    "placeInfo": "string",    "savingsOpportunity": 1.0,    "use": 1.0,    "value": 1.0
  }
  ],  "totalArea": 1.0,  "updated": "2026-03-30",  "useUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  }
}
201 Created The resource was successfully created. The response body contains the new resource.

Response Body Parameters

PlaceGroupDigestBenchmarkRankingResponse
Property Description Type
averageCost The average cost for this group number (double)
averageUse The average use for this group number (double)
benchmarkFactorUnit This will provide the unit for the benchmarking factor eg:ft² or day string
benchmarkUnit This will provide the benchmark unit eg:MMBTU/ft² or $/day string
benchmarkValueUnit This will provide the unit for the benchmark value eg:$ for cost/day, MMBTU for annualized use/area 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 The highest cost for this group number (double)
highUse The highest use for this group number (double)
highValue The highest benchmark value for this group number (double)
lowCost The lowest cost for this group number (double)
lowUse The lowest use for this group number (double)
lowValue The lowest benchmark value for this group number (double)
medianCost The median cost for this group number (double)
medianUse The median use for this group number (double)
medianValue The median benchmark value for this group number (double)
placeGroupCode string
placeGroupDisplay This is the user’s preferred way of viewing this entity - could be code or info based on the master “data object view” setting in DB string
placeGroupId integer (int32)
placeGroupInfo string
results PlaceGroupDigestBenchmarkRankingChild[]
PlaceGroupDigestBenchmarkRankingChild properties
Property Description Type
cost The cost for this place number (double)
includeInCharts boolean
incompleteData Does this place have incomplete data? boolean
placeCode string
placeDisplay string
placeId integer (int32)
placeInfo string
use The use for this place number (double)
value The benchmark value for this place 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,  "averageUse": 1.0,  "benchmarkFactorUnit": "string",  "benchmarkUnit": "string",  "benchmarkValueUnit": "string",  "costUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "highCost": 1.0,  "highUse": 1.0,  "highValue": 1.0,  "lowCost": 1.0,  "lowUse": 1.0,  "lowValue": 1.0,  "medianCost": 1.0,  "medianUse": 1.0,  "medianValue": 1.0,  "placeGroupCode": "string",  "placeGroupDisplay": "string",  "placeGroupId": 1,  "placeGroupInfo": "string",  "results": [
    {    "cost": 1.0,    "includeInCharts": false,    "incompleteData": false,    "placeCode": "string",    "placeDisplay": "string",    "placeId": 1,    "placeInfo": "string",    "use": 1.0,    "value": 1.0
  }
  ],  "updated": "2026-03-30",  "useUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  }
}
202 Accepted The request has been accepted for processing but is not yet complete.

Response Body Parameters

PlaceGroupDigestBenchmarkRankingResponse
Property Description Type
averageCost The average cost for this group number (double)
averageUse The average use for this group number (double)
benchmarkFactorUnit This will provide the unit for the benchmarking factor eg:ft² or day string
benchmarkUnit This will provide the benchmark unit eg:MMBTU/ft² or $/day string
benchmarkValueUnit This will provide the unit for the benchmark value eg:$ for cost/day, MMBTU for annualized use/area 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 The highest cost for this group number (double)
highUse The highest use for this group number (double)
highValue The highest benchmark value for this group number (double)
lowCost The lowest cost for this group number (double)
lowUse The lowest use for this group number (double)
lowValue The lowest benchmark value for this group number (double)
medianCost The median cost for this group number (double)
medianUse The median use for this group number (double)
medianValue The median benchmark value for this group number (double)
placeGroupCode string
placeGroupDisplay This is the user’s preferred way of viewing this entity - could be code or info based on the master “data object view” setting in DB string
placeGroupId integer (int32)
placeGroupInfo string
results PlaceGroupDigestBenchmarkRankingChild[]
PlaceGroupDigestBenchmarkRankingChild properties
Property Description Type
cost The cost for this place number (double)
includeInCharts boolean
incompleteData Does this place have incomplete data? boolean
placeCode string
placeDisplay string
placeId integer (int32)
placeInfo string
use The use for this place number (double)
value The benchmark value for this place 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,  "averageUse": 1.0,  "benchmarkFactorUnit": "string",  "benchmarkUnit": "string",  "benchmarkValueUnit": "string",  "costUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "highCost": 1.0,  "highUse": 1.0,  "highValue": 1.0,  "lowCost": 1.0,  "lowUse": 1.0,  "lowValue": 1.0,  "medianCost": 1.0,  "medianUse": 1.0,  "medianValue": 1.0,  "placeGroupCode": "string",  "placeGroupDisplay": "string",  "placeGroupId": 1,  "placeGroupInfo": "string",  "results": [
    {    "cost": 1.0,    "includeInCharts": false,    "incompleteData": false,    "placeCode": "string",    "placeDisplay": "string",    "placeId": 1,    "placeInfo": "string",    "use": 1.0,    "value": 1.0
  }
  ],  "updated": "2026-03-30",  "useUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  }
}
203 Non-Authoritative Information The request succeeded but the response may be from a cached or secondary source.

Response Body Parameters

PlaceGroupDigestWeatherRankingResponse
Property Description Type
averageNonWeatherLoad number (double)
averageWeatherLoad number (double)
benchmarkFactorUnit This will provide the unit for the benchmarking factor eg:ft² or day string
benchmarkUnit This will provide the benchmark unit eg:MMBTU/ft² or $/day string
benchmarkValueUnit This will provide the unit for the benchmark value eg:$ for cost/day, MMBTU for annualized use/area string
costUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
highNonWeatherLoad number (double)
highWeatherLoad number (double)
lowNonWeatherLoad number (double)
lowWeatherLoad number (double)
medianNonWeatherLoad number (double)
medianWeatherLoad number (double)
placeGroupCode string
placeGroupDisplay This is the user’s preferred way of viewing this entity - could be code or info based on the master “data object view” setting in DB string
placeGroupId integer (int32)
placeGroupInfo string
results PlaceGroupDigestWeatherRankingChild[]
PlaceGroupDigestWeatherRankingChild properties
Property Description Type
baseValue number (double)
includeInCharts boolean
placeCode string
placeDisplay string
placeId integer (int32)
placeInfo string
slopeValue 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 
{  "averageNonWeatherLoad": 1.0,  "averageWeatherLoad": 1.0,  "benchmarkFactorUnit": "string",  "benchmarkUnit": "string",  "benchmarkValueUnit": "string",  "costUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "highNonWeatherLoad": 1.0,  "highWeatherLoad": 1.0,  "lowNonWeatherLoad": 1.0,  "lowWeatherLoad": 1.0,  "medianNonWeatherLoad": 1.0,  "medianWeatherLoad": 1.0,  "placeGroupCode": "string",  "placeGroupDisplay": "string",  "placeGroupId": 1,  "placeGroupInfo": "string",  "results": [
    {    "baseValue": 1.0,    "includeInCharts": false,    "placeCode": "string",    "placeDisplay": "string",    "placeId": 1,    "placeInfo": "string",    "slopeValue": 1.0
  }
  ],  "updated": "2026-03-30",  "useUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  }
}
204 No Content The request succeeded. No content is returned in the response body.