Aggregated Data with Green Button

Aggregated Data

Many people know that Green Button is the definitive international, energy and water data-access and -sharing solution for homes and businesses but many utilities and developers think they need to provide something different for access and sharing of aggregated data.  The Green Button core standard — the NAESB REQ.21 ESPI — already supports aggregated data sharing.

This Developer Resources page provides a concise, step‑by‑step technical overview of two key XML elements in the ESPI schema’s <UsagePoint>(from ESPI) type that allow for sharing aggregated data — and more.

Here, we cover definitions, bit‑level meanings how they complement each other, and we provide XML examples to illustrate typical use cases.

UsagePoint

A <UsagePoint>(from ESPI) in a Green Button XML file represents a metering location or a logical grouping of consumption/generation.

✏️ Note:  If you are, instead, interested in knowing how to determine the Service Location of a meter, you can read more about Mapping Service-Location to a Metered Usage-Point on that Developer Resources page. 

Two metadata elements inside <UsagePoint>(from ESPI) enrich its semantics to allow for representing Aggregated Data:

• • <UsagePoint>(from ESPI)<roleFlags>(from ESPI): this roleFlags element packs up to 16 boolean roles into one HexBinary16 -type value.
    It answers the question of “What roles does this datapoint play?” (EV, DER, mirror, etc.).

• • <UsagePoint>(from ESPI)<isVirtual>(from ESPI): this isVirtual element, if set to “true”, flags that the datapoint is purely logical (i.e., not a physical meter).
    It answers the question “Is this a real, physical meter or a logical grouping of meters?”

A <UsagePoint>(from ESPI) can both be a DER resource and be virtual (e.g., aggregated solar production across a region, multiple tenant meters in a building), or be a physical plug-in electric-vehicle charger (isPEV, explained below), for example, if <isVirtual>false</isVirtual>.

roleFlags element

Type:  xs:HexBinary16 (16 bits)

Purpose:  A compact, 16‑bit field encoding multiple boolean roles.  Each bit represents a distinct role.  Multiple roles combine via bitwise OR’ing, as shown below:

Bit definitions for roleFlags element

Usage-Pattern Example:

• • Filtering for billing systems:  (roleFlags & 0x0800 != 0)?  (this role isRevenueQuality)
  • Filtering for DER meters:  (roleFlags & 0x1000 != 0)?  (this role isDER)
  • Filtering for Aggregated Data:  (roleFlags & 0x4000 != 0)?  (this role isPremisesAggregationPoint)

Combine them and you would test for all three conditions: (roleFlags & 0x0800 & 0x1000 & 0x4000 != 0)?

isVirtual element

Type:  xs:boolean

Purpose:  A simple boolean that distinguishes physical metered points from logical or aggregated ones.  <isVirtual>true</isVirtual> should be used if the datapoint does not represent a physical meter; thus, the <UsagePoint>(from ESPI) is a logical or aggregated container.

Usage-Pattern Examples:

• • Exclude virtual points from GIS/meter‑inventory maps.
  • Treat virtual points as roll‑up totals in billing/forecasting.
  • Label dashboards to distinguish physical vs. aggregated data.

XML Examples

Physical, plug-in electric-vehicle (PEV) charger

<UsagePoint  xmlns="http://naesb.org/espi">
  <roleFlags>2000</roleFlags>   <!-- isPEV bit (0x2000) -->
  <isVirtual>false</isVirtual>  <!-- physical charger -->
  <!-- ... other elements ... -->
</UsagePoint>

Virtual aggregation of premise (facility) meters

<UsagePoint xmlns="http://naesb.org/espi">
  <roleFlags>4000</roleFlags>   <!-- isPremisesAggregationPoint (0x4000) -->
  <isVirtual>true</isVirtual>   <!-- logical aggregation -->
  <!-- Could combine with DER, RevenueQuality, etc. -->
</UsagePoint>

Combined roles: Distributed energy resource (DER) + virtual meter

<UsagePoint xmlns="http://naesb.org/espi">
  <roleFlags>1000</roleFlags>   <!-- isDER (0x1000) -->
  <isVirtual>true</isVirtual>   <!-- no physical meter -->
  <!-- Aggregated renewable generation -->
</UsagePoint>

Premises (facility) aggregation and a revenue-quality reading

<UsagePoint xmlns="http://naesb.org/espi">
  <roleFlags>4800</roleFlags>   <!-- 0x4000 + 0x0800 -->
  <isVirtual>true</isVirtual>   <!-- roll‑up billing point -->
</UsagePoint>

Sample Pseudocode

// Parse hex flags into an integer
int roleFlags = Integer.parseInt(usagePoint.getRoleFlags(), 16);

// Check for revenue-quality
boolean isRevenueQuality = (roleFlags & 0x0800) != 0;

// Check physical vs. virtual
boolean isVirtual = usagePoint.isVirtual();

if (isRevenueQuality && !isVirtual) {
  // then use for billing
}

if ((roleFlags & 0x1000) != 0) {
  // then highlight as a DER resource
}

Need more help with this?  Check-out our Technical Education offerings.