For the complete documentation index, see llms.txt. This page is also available as Markdown.

Insights

Insights

The Insights Report provides a comparative overview of an installation’s overall and disaggregation-category-level energy consumption.

The report answers questions such as:

“How does this installation’s consumption compare with its own past behavior and with other similar installations?”

Insights are generated by comparing the installation against:

  • its own historical consumption from the previous period (self comparison), and

  • the consumption of similar installations with comparable profile characteristics (peer comparison)

Comparisons may be applied to:

  • total electricity delivered from the grid

  • total electricity returned to the grid

  • gas consumption

  • electricity categories

These insights are intended to help end-users better understand their energy behavior and identify opportunities for reduction or improvement.


Key Characteristics

  • Comparative insights The report compares current-period consumption against both historical and peer benchmarks.

  • Self and peer comparison Insights may describe how the installation performs relative to:

    • its previous month or week

    • similar installations in the same peer group

  • Multi-domain coverage Comparisons may apply to electricity, gas and disaggregation categories.

  • NET2GRID EnergyAI® estimation Insights are derived from disaggregation results and profile-based clustering.


Understanding the Data

Each insight represents a comparison between the installation’s current usage and a benchmark value.

The report may contain:

  • Self insights Comparing the current period with the installation’s own previous period

  • Peer insights Comparing the current period with the median usage of similar installations

Each insight contains:

  • the actual usage for the current period

  • the benchmark value

  • the difference in kWh

  • the difference in percentage

  • a status indicating the severity of the deviation

  • a relevance score indicating how important the insight is for the installation


Report Generation Logic

Monthly Insights

  • The monthly report is generated once per month

  • It covers the previous calendar month

  • It is generated only if new measurement data became available for the installation during that month

Weekly Insights

  • The weekly report is generated once per week

  • It covers the previous week (Monday–Sunday)

  • It is generated only if new measurement data became available for the installation during that week

  • By default, the weekly insights functionality is disabled.


Requirements

The Insights Report is generated only if measurement data is available for the reporting period.


Installation Profile Impact

Peer Comparison

For peer comparison to be available, the following minimum profile information is required:

  • Country

  • Postal Code

  • Number of Occupants

  • Property Type

  • Property Age

If this information is missing, peer insights may not be available.


Technical Specifications

Storage Location

Monthly Reports

The monthly insights reports are generated under the S3 export bucket using the following format:

s3://{exportBucket}/{labelpartner}/reports/{installationIdentifier}/{serviceType}/insights/{filename}

Path Parameters

  • exportBucket: the name of the AWS S3 bucket that contains the reports

  • labelpartner: the identifier of the label partner

  • installationIdentifier: the external installation identifier provided during end-user provisioning

  • serviceType: SM

Filename Format

{internalInstallationIdentifier}_{reportMonth}_insights.json

Where:

  • internalInstallationIdentifier: the internal installation identifier used in NET2GRID EnergyAI®

  • reportMonth: the reporting month in YYYYMM format


Weekly Reports

The weekly insights reports are generated under the following format:

s3://{exportBucket}/{labelpartner}/reports/{installationIdentifier}/{serviceType}/weekly-insights/{filename}

Weekly Filename Format

{internalInstallationIdentifier}_{reportWeek}_weekly_insights.json

Where:

  • reportWeek: the reporting week in xxxxWww ISO-8601 format


Report Format

The report is provided in JSON format.

Main Fields

Field
Type
Monthly
Weekly
Description

year

integer

true

false

The year under examination.

month

integer

true

false

The month under examination.

week

string

false

true

The week under examination in xxxxWww ISO-8601 format.

error

string

true

true

Error code returned for the report.

timestamp

long

true

true

UNIX timestamp in milliseconds indicating when the report was produced and published.

serviceType

string

true

true

SM

version

string

true

true

Service version, e.g. 2.3.

clusterId

string

true

true

Unique identifier of the peer comparison cluster to which the installation belongs.

insights

list

true

true

List of calculated InsightReportObjects for the installation and reporting period.


InsightReportObjects

Each insight object contains:

Field
Type
Description

id

string

Insight identifier in the format aa-t-pp, where: aa is the disaggregation category code, t is the timeOfUse code (Currently only T is supported), and pp is the comparison type code

appliance

string

Disaggregation Category or total, depending on the insight.

type

string

Insight type: self or peer.

timeOfUse

string

Time-of-use dimension of the insight. Currently: total.

data

list

List of InsightData objects.

status

string

Status level of the insight, from 0 (Very low) to 6 (Very high).

relevance

float

Relevance score of the insight for the installation. Higher values indicate higher importance.

isPositive

boolean

Indicates whether the insight reflects a positive relevance (bad practice) or a negative relevance (good practice).


Disaggregation Categories Codes

Code
Description

TE

Total Electricity Delivered

AON

Always On

RFR

Refrigeration

LIG

Lighting

ENT

Entertainment

LAU

Laundry

COO

Cooking

EV

Electric Vehicle

WH

Water Heating

SH

Space Heating

OTH

Other

TG

Total Gas Delivered

COOG

Cooking using Gas

SHG

Space Heating using Gas

WHG

Water Heating using Gas

Comparison Type Codes (pp)

Code
Description

PP

Self comparison

Ot

Peer comparison


InsightData Object

Each InsightData object contains one metric used in the comparison.

Field
Type
Description

name

string

Metric name. Supported values: benchmark, usage, deltaKwh, deltaPerc.

value

float

Metric value.

Supported InsightData Metrics

Name
Description

benchmark

Benchmark value used for the comparison. For self insights, this is the previous period’s consumption. For peer insights, this is the peer group median.

usage

Actual energy consumption value for the current reporting period.

deltaKwh

Absolute difference between usage and benchmark (usage - benchmark).

deltaPerc

Relative difference between usage and benchmark (deltaKwh / benchmark).


Error Codes

Code
Message
Monthly Applicable
Weekly Applicable
Insights Provided
Description

null

-

true

true

true

No error occurred during report generation.

30002

Erroneous Profile Info

true

true

false

One or more profile values are excessive, inconsistent, or unrealistic.

30003

No Current Period Disaggregation Document Available

true

true

false

No measurements are available for the installation for the requested reporting period.

30004

Excessive Value on Disaggregation Document

true

true

false

The total energy consumption value for the requested reporting period is abnormally high and considered invalid.

30005

Negative Value on Disaggregation Document

true

true

false

The total energy consumption value for the requested reporting period is negative.

40001

Incomplete Profile for Insights Reports

true

true

false

Essential profile information required for insights is missing or invalid.

40002

No Peer Installations Available for Comparison

true

true

true

No peer installations are available in the same comparison group. Self comparison only is provided.

40003

No Previous Period Consumption Available for Comparison

true

true

true

No previous period consumption is available for self comparison. Peer comparison only is provided.

40004

No Peer Installations and Previous Period's Measurements Available for Comparison

true

true

false

Neither peer comparison nor self comparison can be generated.


Notes

  • Monthly Applicable indicates whether the error code may appear in monthly insights reports.

  • Weekly Applicable indicates whether the error code may appear in weekly insights reports.

  • Insights Provided indicates whether the report still contains insight results.


Example Report Files

Example Monthly Report File

A monthly insights report may be generated in a location such as:

s3://s3-export-ABC/labelpartnerB/reports/installationX/SM/insights/abc123456_202304_insights.json

Example data:


Example Weekly Report File

A weekly insights report may be generated in a location such as:

s3://s3-export-ABC/labelpartnerB/reports/installationX/SM/weekly-insights/abc123456_2023W01_weekly_insights.json

Example contents:


Notification Mechanism

Monthly Reports

A message is published when a monthly insights report is generated.

Queue: insights_{labelpartner}

Message Format

Routing key:

{installationIdentifier}.insights


Weekly Reports

A message is published when a weekly insights report is generated.

Queue: weekly_insights_{labelpartner}

Message Format

Routing key:

{installationIdentifier}.weekly_insights

Last updated

Was this helpful?