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

    • 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

  • The monthly insights 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


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

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


Report Format

The report is provided in JSON format.

Main Fields

Field
Type
Description

year

integer

The year under examination.

month

integer

The month under examination.

error

string

Error code returned for the report.

timestamp

long

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

serviceType

string

SM

version

string

Service version, e.g. 2.3.

clusterId

string

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

insights

list

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
Insights Provided
Description

null

-

true

No error occurred during report generation.

30002

Erroneous Profile Info

false

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

30003

No Current Period Disaggregation Document Available

false

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

30004

Excessive Value on Disaggregation Document

false

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

30005

Negative Value on Disaggregation Document

false

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

40001

Incomplete Profile for Insights Reports

false

Essential profile information required for insights is missing or invalid.

40002

No Peer Installations Available for Comparison

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

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

false

Neither peer comparison nor self comparison can be generated.

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


Example Report Files

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:


Notification Mechanism

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

Queue: insights_{labelpartner}

Message Format

Routing key:

{installationIdentifier}.insights

Last updated

Was this helpful?