system.mes.meter.calculateMeterSummary

Description

Calculates a comprehensive meter summary of usage and cost within a date range with optional filters and unit conversions. Returns aggregated totals, rates, and peak and minimum values for the period.

Permissions

This method requires the METERING.READ.CALCULATE permission.

Syntax

system.mes.meter.calculateMeterSummary(startDate, endDate, equipmentIdOrPath=None, locationIdOrPath=None, meterTypeIdOrName=None, meterIdOrName=None, statuses=None, targetUsageUomIdOrName=None, targetCostUomIdOrName=None)

Parameters

Parameter	Type	Nullable	Description
startDate	Date	False	Start date (inclusive) as a Date object or milliseconds since epoch.
endDate	Date	False	End date (inclusive) as a Date object or milliseconds since epoch.
equipmentIdOrPath	String	True	Filter by equipment ID or path.
locationIdOrPath	String	True	Filter by location ID or path.
meterTypeIdOrName	String	True	Filter by meter type ID or name.
meterIdOrName	String	True	Filter by meter record ID or name.
statuses	List<String>	True	Filter by status values (e.g., ['RUNNING', 'COMPLETED']).
targetUsageUomIdOrName	String	True	Target unit of measure ID or name for usage conversion. If omitted, uses the most frequent unit from matched records.
targetCostUomIdOrName	String	True	Target unit of measure ID or name for cost conversion. If omitted, uses the most frequent unit from matched records.

Returns

Returns a JSON object containing the meter summary.

Name	Type	Description
startDate	Instant	Start date (inclusive) of the summary window.
endDate	Instant	End date (inclusive) of the summary window.
totalUsage	Double	Total usage accumulated during the summary window.
totalCost	Double	Total cost accumulated during the summary window.
averageCostPerUsage	Double	Average cost per usage unit (totalCost / totalUsage).
usageUnitOfMeasureName	String	Name of the usage unit of measure.
usageUnitOfMeasureSymbol	String	Symbol of the usage unit of measure.
costUnitOfMeasureName	String	Name of the cost unit of measure.
costUnitOfMeasureSymbol	String	Symbol of the cost unit of measure.
recordCount	Integer	Number of Meter Records included in this summary.
totalDurationSec	Double	Total duration across all records in seconds.
averageUsagePerSecond	Double	Average usage rate per second.
averageCostPerSecond	Double	Average cost rate per second.
peakUsagePerSecond	Double	Peak (maximum) usage rate per second across all records.
minUsagePerSecond	Double	Minimum usage rate per second across all records.
peakCostPerSecond	Double	Peak (maximum) cost rate per second across all records.
minCostPerSecond	Double	Minimum cost rate per second across all records.
peakCostPerUsage	Double	Peak cost per usage unit across all records.
minCostPerUsage	Double	Minimum cost per usage unit across all records.

Code Examples

# Calculate a 30-day electricity usage summary for a specific piece of equipment
startDate = system.date.addDays(system.date.now(), -30)
endDate = system.date.now()

summary = system.mes.meter.calculateMeterSummary(
    startDate,
    endDate,
    equipmentIdOrPath='Enterprise/Site/Line1',
    meterTypeIdOrName='Electricity'
)

print("Total Usage:", summary['totalUsage'], summary['usageUnitOfMeasureSymbol'])
print("Total Cost:", summary['totalCost'], summary['costUnitOfMeasureSymbol'])
print("Average Rate (per sec):", summary['averageUsagePerSecond'])
print("Peak Rate (per sec):", summary['peakUsagePerSecond'])
print("Record Count:", summary['recordCount'])