system.mes.meter.calculateMeterSummaryByTimeInterval

Description

Calculates meter summaries bucketed by a specified time interval within a date range with optional filters. Returns a list of summary objects, one per interval bucket, each containing the same comprehensive metrics as calculateMeterSummary.

Permissions

This method requires the METERING.READ.CALCULATE permission.

Syntax

system.mes.meter.calculateMeterSummaryByTimeInterval(startDate, endDate, interval, intervalTimeUnits, 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.
interval	Integer	False	Duration of each time bucket. Must be greater than 0.
intervalTimeUnits	String	False	Time unit for the interval. One of: SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, YEARS.
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 list of JSON objects, one per time interval bucket. Each object has the following properties:

Name	Type	Description
startDate	Instant	Start date (inclusive) of this interval bucket.
endDate	Instant	End date (inclusive) of this interval bucket.
totalUsage	Double	Total usage accumulated during this interval.
totalCost	Double	Total cost accumulated during this interval.
averageCostPerUsage	Double	Average cost per usage unit for this interval.
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 interval.
totalDurationSec	Double	Total duration across all records in this interval in seconds.
averageUsagePerSecond	Double	Average usage rate per second for this interval.
averageCostPerSecond	Double	Average cost rate per second for this interval.
peakUsagePerSecond	Double	Peak (maximum) usage rate per second across records in this interval.
minUsagePerSecond	Double	Minimum usage rate per second across records in this interval.
peakCostPerSecond	Double	Peak (maximum) cost rate per second across records in this interval.
minCostPerSecond	Double	Minimum cost rate per second across records in this interval.
peakCostPerUsage	Double	Peak cost per usage unit across records in this interval.
minCostPerUsage	Double	Minimum cost per usage unit across records in this interval.

Code Examples

# Calculate daily electricity usage summaries for the past 7 days
startDate = system.date.addDays(system.date.now(), -7)
endDate = system.date.now()

summaries = system.mes.meter.calculateMeterSummaryByTimeInterval(
    startDate,
    endDate,
    1,
    'DAYS',
    equipmentIdOrPath='Enterprise/Site/Line1',
    meterTypeIdOrName='Electricity'
)

# Output the daily usage for each day
for dailySummary in summaries:
    print("Date:", dailySummary['startDate'], "Usage:", dailySummary['totalUsage'], dailySummary['usageUnitOfMeasureSymbol'])