Utility Bill Data
Mapping Utility Billing Data to the UsageSummary Resource XML Format
Introduction
Utility billing statements are an essential source of energy usage data for residential and commercial customers. However, there is no industry-defined standard format for the data contained in utility billing statements, nor how they are presented. This lack of standardization challenges developers who need to process these data for energy reporting and analysis.
The Green Button UsageSummary resource (<UsageSummary>) addresses these challenges by providing a structured, standardized XML format summarizing energy usage for a billing period.
Let’s explore how to map utility billing data to the Green Button <UsageSummary> XML format. Whether you’re a developer or utility professional, this guide will help streamline your data-processing workflows and ensure compatibility with the Green Button standard.
Table of Contents
Understanding the Utility Billing Data
Utility billing statements typically contain the following types of data:
-
-
Service Period: The dates defining the billing period (e.g., Nov 9, 2024 – Dec 10, 2024).
-
Energy Usage: The total energy consumed during the billing period (e.g., 347 kWh).
-
Charges and Fees: A breakdown of costs, such as current service charges, environmental compliance fees, and sales tax.
-
Meter Details: Information about readings, such as start and end readings and reading types (e.g., total kWh).
-
Each utility may organize and label this data differently. A flexible parsing framework that uses configurable templates or mappings is recommended to handle variability effectively. This approach ensures consistent output even when utility data formats differ.
Target Structure: Green Button UsageSummary
The Green Button <UsageSummary> resource (from the ESPI Schema) provides a standardized way to summarize energy usage for a billing period. Utilities may implement this resource in varying ways:
-
- Frequent Inclusion: Some utilities include the
<UsageSummary>in every data transmission, reflecting the last billing period. - Post-Billing Period: Others only include it in the first response after a billing period.
- Frequent Inclusion: Some utilities include the
Billing periods often align with a customer’s move-in date, meaning each account may have a unique cycle. The <UsageSummary> can be associated with either a single <UsagePoint> or multiple <UsagePoints>, as defined by the <link> element (in the associated Atom feed):
-
- Single UsagePoint: The
type=attribute contains"espi-entry/UsagePoint". - Multiple UsagePoints: The
type=attribute contains"espi-feed/UsagePoint".
- Single UsagePoint: The
UsageSummary - Key Fields
Key fields in the <UsageSummary> XML format includes:
-
<billingPeriod>: Includes a duration (in seconds) and a start (epoch timestamp without time-zone adjustments).<billLastPeriod>: The monetary amount for the last billing period reported in hundred-thousandths of the currency chosen (see Cost and Currency for more on this topic).<billToDate>: The total billing amount for the current period to date. This can be omitted if the utility only reports the billing data for the last period.<costAdditionalLastPeriod>: Sum of additional charges, such as taxes or administrative fees, also reported in hundred-thousandths of the monetary currency (see Cost and Currency for more on this topic).<costAdditionalDetailLastPeriod>: A dynamic structure for including specific non-personally identifiable details, and consists of the following elements:<amount>: Used to report monetary amounts.
All monetary amounts are reported in hundred-thousandths of the chosen currency (see Cost and Currency for more).<rounding>: Rounded value for amounts if needed.<dateTime>: Significant dates in epoch UTC format.<note>: Descriptions from the utility bill.<measurement>: Used to report consumption amounts and includes the following elements:<powerOfTenMultiplier>: An enumeration representing the multiplier for the unit of measure:- “-12” = Pico (p), (VS ×️ 10(-12))
- “-9” = Nano (n), (VS ×️ 10(-9))
- “-6” = Micro (micro), (VS ×️ 10(-6))
- “-5” = currency, (VS ×️ 10(-5)) — technically not a part of the enumeration
- “-3” = Milli (m), (VS ×️ 10(-12))
- “-2” = Centi (c), (VS ×️ 10(-2))
- “-1” = Deci (d), (VS ×️ 10(-1))
- “3” = Kilo (k), (VS ×️ 103)
- “6” = Mega (M), (VS ×️ 106)
- “9” = Giga (G), (VS ×️ 109)
- “12” = Tera (T), (VS ×️ 1012)
- “0” = Not Applicable (none), (VS ×️ 100)
- “1” = deca (da), (VS ×️ 101)
- “2” = hecto (h), (VS ×️ 102)
<timestamp>: The time of the measurement in epoch UTC format.<uom>: An enumeration for the unit of measurement (e.g., “72” for “Wh”).<value>: The value of the summary measurement.<ReadingTypeRef>: An optional URL string matching the related<ReadingType>of
the Atom…<link rel="self" type="espi-entry/ReadingPoint" href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/ReadingType/71b40a68-b160-596b-bb71-d9708af967df"/>
…attribute entry of the related<UsagePoint>.
The71b40a68-b160-596b-bb71-d9708af967dfUUID is just an example. You can see the example of this use in the “Current Service”, Step 3, XML example; toward the end of this page.
<itemKind>: An enumeration of the ItemKind type, which can be one of the following:- Fees:
(always represented in the XML as a positive integer)- “1” = Energy Generation Fee
- “2” = Energy Delivery Fee
- “3” = Energy Usage Fee
- “4” = Administrative Fee
- “5” = Tax
- Credits:
(treated as a negative number for the<costAdditionalDetailLastPeriod> <amount>elements but always represented in the XML as a positive integer)- “6” = Energy Generation Credit
- “7” = Energy Delivery Credit
- “8” = Administrative Credit
- “9” = Payment
- Non-Charge/Non-Credit:
- “10” = Information
- Fees:
<unitCost>: The per-unit cost amount is reported in hundred-thousandths of the chosen currency (see Cost and Currency for more on this topic).<itemPeriod>: The period covered by the line item. This is used to support pricing changes in the middle of the billing period.<duration>: The duration of the period is reported in seconds.<start>: The date and time that the period started, reported as an epoch UTC timestamp.
<currency>: An enumeration of the CurrencyCode type, which mirrors ISO 4217 to indicate the currency applicable to the currency amounts reported:- “124” = Canadian Dollar (CAD)
- “410” = South Korean Won (KRW)
- “840” = United States Dollar (USD)
- “978” = European Euro (EUR)
- etc. (see Cost and Currency for more on this topic).
<overallConsumptionLastPeriod>: Reports total consumption for the last billing period and includes elements that are similar to those in the<costAdditionalDetailLastPeriod> <measurement>element.
Mapping Utility Billing Data to the ESPI UsageSummary Resource
The following section demonstrates how to map monthly Electricity or Natural Gas -statement data to the ESPI <UsageSummary> resource.
The data in the example were obtained from actual monthly electricity and natural gas statements — altered for privacy reasons but containing the original informational categories.
Step 1 - Extract the Data from the Utility Bill
Let’s use the above sample utility bill as a reference:
-
-
Billing Period: Nov 9, 2024 – Dec 10, 2024
- 31 days (31d × 24h × 60m × 60s = 2678400 seconds)
- “Nov 9, 2024” at 12:00:00 AM Eastern Time (UTC-05:00) is the Start Date and Time
- This is represented in Unix, Epoch Time: seconds-from 1971-01-01 UTC (Universal Time Coordinated)
- The Bill’s Start Date/Time, interpreted: Saturday, November 9, 2024 at 12:00:00 AM (UTC-05:00)
- The Actual Start Date/Time, transmitted: Saturday, November 9, 2024 at 5:00:00 AM UTC as “1731128400”
-
Total Energy Usage: 347 kWh
- 347000 Wh
-
“Current Electric Service” & “Total Due”: $68.27 (in USD)
- “Previous Bill Amount” = $72.51
- “Payment Received On 12/04/24 Thank You!” = $72.51
- “Current Service” = $56.52
- “Environmental Compliance Cost” = $4.82
- “Municipal Franchise Fee” = $1.88
- “Sales Tax” = $5.05
-
Meter Details:
- Reading Type = “Tot kWh”
- Previous (Start Reading) = 34489
- Current (End Reading) = 34836
-
Step 2 - Map the Extracted Data to UsageSummary Fields
In this table, the mapping is not exactly from the bill; rather, the mapping is to the bill. For example: In each <costAdditionalDetailLastPeriod> element, there are monetary values that are calculated from fees/charges. Those calculations result in fractions of cents (e.g., “Current Service” totals $56.519362 from a cost of electricity of $0.16288/kWh) which are then rounded to the number of places defined by <rounding> by the receiver of the data (the Customer or the Green Button Third Party service/app provider).
| Utility-Bill Wording | Green Button Equivalent | UsageSummary Field & Example-Bill XML Value | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| (Dec 10, 2024) − (Nov 9, 2024) |
Billing period Duration (31 days, in seconds) |
|
|||||||||||||||||||||||||||||||||||||||||||||
| Billing Period: “Nov 9, 2024” |
Billing Period, Start Date |
|
|||||||||||||||||||||||||||||||||||||||||||||
| Total Due: “$68.27” |
Total Due (as hundred-thousandths: (CS × 10⁽⁻⁵⁾), ( × 0.00001) |
|
|||||||||||||||||||||||||||||||||||||||||||||
|
+ “Previous Bill Amount” − “Payment Received On 12/04/24 Thank You!” + “Current Service” + “Environmental Compliance Cost” + “Municipal Franchise Fee” + “Sales Tax” |
Additional Charges + 7251000 |
|
|||||||||||||||||||||||||||||||||||||||||||||
|
“Previous Bill Amount” Additional Charge, Detail |
|
||||||||||||||||||||||||||||||||||||||||||||||
|
“Payment Received On 12/04/24 Thank You!” Additional Charge, Detail |
|
||||||||||||||||||||||||||||||||||||||||||||||
|
“Current Service” Additional Charge, Detail |
|
||||||||||||||||||||||||||||||||||||||||||||||
|
“Environmental Compliance Cost” Additional Charge, Detail |
|
||||||||||||||||||||||||||||||||||||||||||||||
|
“Municipal Franchise Fee” Additional Charge, Detail |
|
||||||||||||||||||||||||||||||||||||||||||||||
|
“Sales Tax” Additional Charge, Detail |
|
||||||||||||||||||||||||||||||||||||||||||||||
| Total Due: “$68.27” |
Currency of the Total Due (USD because bill is in USA) |
|
|||||||||||||||||||||||||||||||||||||||||||||
| Meter Reading: Reading Type: “Tot kWh” |
Total Consumption Scaling, kWh (VS × 10x) |
|
|||||||||||||||||||||||||||||||||||||||||||||
| Meter Reading: Reading Type: “Tot kWh” |
Total Consumption Units, unscaled (“Wh”) because kWh is not an acceptable UOM for Green Button. |
|
|||||||||||||||||||||||||||||||||||||||||||||
| Meter Reading: Usage: “347” |
Total Consumption Raw, Sent Value (VS) |
|
|||||||||||||||||||||||||||||||||||||||||||||
| “2024-12-10 T23:59:59Z” |
Date/Time status of this UsageSummary in seconds from 1970-01-01 T00:00:00Z |
|
|||||||||||||||||||||||||||||||||||||||||||||
Step 3 - Generate the UsageSummary XML
Here’s a Green Button XML segment showing how fixed billing data are reported:
<!-- snippet from Energy Usage data file/stream -->
<entry>
<id>urn:uuid:3d8aed62-26a7-589a-9473-98f02ef82dc2</id>
<link rel="up" type="espi-feed/UsageSummary"
href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/d08a5072-d5ac-5647-9b30-2a23cf3bd5e6/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c/UsageSummary"/>
<link rel="self" type="espi-entry/UsageSummary"
href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/d08a5072-d5ac-5647-9b30-2a23cf3bd5e6/UsagePoint/463e8f00-e483-5439-baae-1b718abba15c/UsageSummary/3c219aab-c147-5897-a25c-636ac7a28691"/>
<link rel="related" type="espi-feed/UsagePoint"
href="https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/Subscription/d08a5072-d5ac-5647-9b30-2a23cf3bd5e6/UsagePoint"/>
<title>Billing Period: Nov 9 - Dec 10</title>
<content>
<UsageSummary xmlns="http://naesb.org/espi">
<!-- Billing Period & Cost, as denoted on the bill -->
<billingPeriod>
<duration>2678400</duration>
<!-- 31 days exactly -->
<start>1731128400</start>
<!-- 09 November 2024 at midnight in local time (but 5AM UTC) -->
</billingPeriod>
<billLastPeriod>6827000</billLastPeriod>
<!-- total charge of this bill in hundred thousandths -->
<costAdditionalLastPeriod>6827000</costAdditionalLastPeriod>
<!-- aggregation (total due) of all bill charges, in hundred thousandths -->
<!-- Line Item: “Previous Bill Amount” = $72.51 -->
<costAdditionalDetailLastPeriod>
<amount>7251000</amount>
<!-- total for the duration -->
<rounding>2</rounding>
<!-- two places -->
<dateTime>1733875199</dateTime>
<!-- 10 December 2024 last-second before midnight -->
<note xml:space="preserve">Previous Bill Amount</note>
<!-- line-item description from the bill -->
<measurement> <!-- the bill has only a single measurement for the duration -->
<powerOfTenMultiplier>-5</powerOfTenMultiplier>
<!-- ‘value’ is represented as hundred-thousandths of the chosen currency -->
<timeStamp>1733875199</timeStamp>
<!-- 10 December 2024 last-second before midnight -->
<uom>80</uom>
<!-- unit of measure is “money” -->
<value>7251000</value>
<!-- value of the summary measurement -->
</measurement>
<itemKind>3</itemKind>
<!-- “Energy Usage Fee” because it includes all charges from past billing -->
<itemPeriod> <!-- for this charge, which is the entire bill duration in this case -->
<duration>2678400</duration>
<!-- 31 days exactly -->
<start>1731128400</start>
<!-- 09 November 2024 at midnight in local time (but 5AM UTC) -->
</itemPeriod>
</costAdditionalDetailLastPeriod>
<!-- Line Item: “Payment Received On 12/04/24 Thank You!” = -$72.51 -->
<costAdditionalDetailLastPeriod> <!-- line-item for bill credit -->
<amount>7251000</amount>
<!-- total for the duration -->
<rounding>2</rounding>
<!-- two places -->
<dateTime>1733875199</dateTime>
<!-- 10 December 2024 last-second before midnight -->
<note xml:space="preserve">Payment Received On 12/04/24 Thank You!</note>
<!-- line-item description from the bill,
and because the bill has the extra spaces before Thank You, we preserve them here;
though it is not an ESPI requirement -->
<measurement> <!-- the bill has only a single measurement for the duration -->
<powerOfTenMultiplier>-5</powerOfTenMultiplier>
<!-- ‘value’ is represented as hundred-thousandths of the chosen currency -->
<timeStamp>1733875199</timeStamp>
<!-- 10 December 2024 last-second before midnight -->
<uom>80</uom>
<!-- unit of measure is “money” -->
<value>7251000</value>
<!-- value of the summary measurement -->
</measurement>
<itemKind>9</itemKind>
<!-- “Payment” treated as a negative number -->
<itemPeriod> <!-- for this credit, which is the entire bill duration in this case -->
<duration>2678400</duration>
<!-- 31 days exactly -->
<start>1731128400</start>
<!-- 09 November 2024 at midnight in local time (but 5AM UTC) -->
</itemPeriod>
</costAdditionalDetailLastPeriod>
<!-- Line Item: “Current Service” = $56.52 -->
<costAdditionalDetailLastPeriod> <!-- line-item for bill charge -->
<amount>5651936</amount>
<!-- total for the duration: $56.51936 -->
<rounding>2</rounding>
<!-- for display: round the ‘amount’ to two places: $56.52 -->
<dateTime>1733875199</dateTime>
<!-- 10 December 2024 last-second before midnight -->
<note xml:space="preserve">Current Service</note>
<!-- line-item description from the bill -->
<measurement> <!-- the bill has only a single measurement for the duration -->
<powerOfTenMultiplier>-5</powerOfTenMultiplier>
<!-- ‘value’ is represented as hundred-thousandths of the chosen currency -->
<timeStamp>1733875199</timeStamp>
<!-- 10 December 2024 last-second before midnight -->
<uom>80</uom>
<!-- unit of measure is “money” -->
<value>5651936</value>
<!-- value of the summary measurement -->
<readingTypeRef>https://data.greenbuttonconnect.org/DataCustodian/espi/1_1/resource/ReadingType/71b40a68-b160-596b-bb71-d9708af967df</readingTypeRef>
<!-- reference back to the ReadingType for this measurement -->
</measurement>
<itemKind>1</itemKind>
<!-- “Energy Generation Fee” -->
<unitCost>16288</unitCost>
<!-- electricity is $0.16288/kWh; thus, 0.16288 ÷ 10⁽⁻⁵⁾ = 16288
We know the units (kWh) from the scaling provided by
the <overallConsumptionLastPeriod> <powerOfTenMultiplier> and by
the base units defined by <overallConsumptionLastPeriod> <uom> -->
<itemPeriod> <!-- for this charge, which is the entire bill duration in this case -->
<duration>2678400</duration>
<!-- 31 days exactly -->
<start>1731128400</start>
<!-- 09 November 2024 at midnight in local time (but 5AM UTC) -->
</itemPeriod>
</costAdditionalDetailLastPeriod>
<!-- Line Item: “Environmental Compliance Cost” = $4.82 -->
<costAdditionalDetailLastPeriod> <!-- line-item for bill charge -->
<amount>482116</amount>
<!-- total for the duration: $4.82116 -->
<rounding>2</rounding>
<!-- for display: round the ‘amount’ to two places: $4.82 -->
<dateTime>1733875199</dateTime>
<!-- 10 December 2024 last-second before midnight -->
<note xml:space="preserve">Environmental Compliance Cost</note>
<!-- line-item description from the bill -->
<measurement> <!-- the bill has only a single measurement for the duration -->
<powerOfTenMultiplier>-5</powerOfTenMultiplier>
<!-- ‘value’ is represented as hundred-thousandths of the chosen currency -->
<timeStamp>1733875199</timeStamp>
<!-- 10 December 2024 last-second before midnight -->
<uom>80</uom>
<!-- unit of measure is “money” -->
<value>482116</value>
<!-- value of the summary measurement -->
</measurement>
<itemKind>4</itemKind>
<!-- “Administrative Fee” -->
<unitCost>8530</unitCost>
<!-- this particular charge is 8.53%; thus, 0.0853 ÷ 10⁽⁻⁵⁾ = 8530 -->
<itemPeriod>
<!-- for this charge, which is the entire bill duration in this case -->
<duration>2678400</duration>
<!-- 31 days exactly -->
<start>1731128400</start>
<!-- 09 November 2024 at midnight in local time (but 5AM UTC) -->
</itemPeriod>
</costAdditionalDetailLastPeriod>
<!-- Line Item: “Municipal Franchise Fee” = $1.88 -->
<costAdditionalDetailLastPeriod> <!-- line-item for bill charge -->
<amount>187986</amount>
<!-- total for the duration: $1.87986 -->
<rounding>2</rounding>
<!-- for display: round the ‘amount’ to two places: $1.88 -->
<dateTime>1733875199</dateTime>
<!-- 10 December 2024 last-second before midnight -->
<note xml:space="preserve">Municipal Franchise Fee</note>
<!-- line-item description from the bill -->
<measurement> <!-- the bill has only a single measurement for the duration -->
<powerOfTenMultiplier>-5</powerOfTenMultiplier>
<!-- ‘value’ is represented as hundred-thousandths of the chosen currency -->
<timeStamp>1733875199</timeStamp>
<!-- 10 December 2024 last-second before midnight -->
<uom>80</uom>
<!-- unit of measure is “money” -->
<value>187986</value>
<!-- value of the summary measurement -->
</measurement>
<itemKind>4</itemKind>
<!-- “Administrative Fee” -->
<unitCost>3326</unitCost>
<!-- this particular charge is 3.3263%; thus, 0.033263 ÷ 10⁽⁻⁵⁾ = 3326.3 which
must be rounded to the nearest integer: 3326 -->
<itemPeriod> <!-- for this charge, which is the entire bill duration in this case -->
<duration>2678400</duration>
<!-- 31 days exactly -->
<start>1731128400</start>
<!-- 09 November 2024 at midnight in local time (but 5AM UTC) -->
</itemPeriod>
</costAdditionalDetailLastPeriod>
<!-- Line Item: “Sales Tax” = $5.05 -->
<costAdditionalDetailLastPeriod> <!-- line-item for bill charge -->
<amount>505000</amount>
<!-- total for the duration -->
<rounding>2</rounding>
<!-- two places -->
<dateTime>1733875199</dateTime>
<!-- 10 December 2024 last-second before midnight -->
<note xml:space="preserve">Sales Tax</note>
<!-- line-item description from the bill -->
<measurement> <!-- the bill has only a single measurement for the duration -->
<powerOfTenMultiplier>-5</powerOfTenMultiplier>
<!-- ‘value’ is represented as hundred-thousandths of the chosen currency -->
<timeStamp>1733893199</timeStamp>
<!-- 10 December 2024 last-second before midnight in local time
(but 11 Dec. at 4:59:59 UTC) -->
<uom>80</uom>
<!-- unit of measure is “money” -->
<value>505000</value>
<!-- value of the summary measurement -->
</measurement>
<itemKind>5</itemKind>
<!-- “Tax” -->
<unitCost>8000</unitCost>
<!-- this particular tax rate is 8%; thus, 0.08 ÷ 10⁽⁻⁵⁾ = 8000 -->
<itemPeriod> <!-- for this charge, which is the entire bill duration in this case -->
<duration>2678400</duration>
<!-- 31 days exactly -->
<start>1731128400</start>
<!-- 09 November 2024 at midnight in local time (but 5AM UTC) -->
</itemPeriod>
</costAdditionalDetailLastPeriod>
<currency>840</currency>
<!-- US Dollars, for this bill (based on location of service) -->
<overallConsumptionLastPeriod>
<powerOfTenMultiplier>3</powerOfTenMultiplier>
<!-- desired, scaled unit of “kWh” (e.g., “347 kWh”) -->
<uom>72</uom>
<!-- base unit of “Wh” -->
<value>347</value>
<!-- transmited in XML -->
</overallConsumptionLastPeriod>
<qualityOfReading>19</qualityOfReading>
<!-- “revenue quality” -->
<statusTimeStamp>1733875199</statusTimeStamp>
<!-- 10 December 2024 last-second before midnight in local time
(but 11 Dec. at 4:59:59AM UTC) -->
</UsageSummary>
</content>
<published>2024-12-11T04:59:59Z</published>
<!-- 10 December 2024 last-second before midnight in local time
(but 11 Dec. at 4:59:59AM UTC) -->
<updated>2024-12-11T04:59:59Z</updated>
<!-- same as the published date because no updated or corrected data were issued -->
</entry>Closing Thoughts
Mapping utility billing data to the Green Button UsageSummary format ensures compatibility with Green Button standards-compliant systems and it enables standardized energy-data reporting.
Although there are additional elements under <UsageSummary> available — including:
-
- Ratchet Demand,
- Commodity Type,
- Tariff Profile, and others
— this article outlined the steps for extracting, mapping, and transforming the most-common utility data into a compliant Green Button XML structure.
Additionally, you may have noticed in the code example, there is a <ReadingTypeRef> inside the <costAdditionalDetailLastPeriod> for the “Current Service” Line Item, which is not shown in the table. The description of this field is found in the UsageSummary - Key Fields section (see the Table of Contents for reference).
For further guidance and resources, view our other Green Button Alliance Developer Resources, using the link, below.