Utility Bill Data

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>ESPI) 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>ESPI 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.

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 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.

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>Atom element (in the associated Atom feed):

• • Single UsagePoint: The type= attribute contains "espi-entry/UsagePoint".
  • Multiple UsagePoints: The type= attribute contains "espi-feed/UsagePoint".

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), (V_S ×️ 10^(-12))
        •   “-9”  = Nano (n), (V_S ×️ 10^(-9))
        •   “-6”  = Micro (micro), (V_S ×️ 10^(-6))
        •   “-3”  = Milli (m), (V_S ×️ 10^(-12))
        •   “-2”  = Centi (c), (V_S ×️ 10^(-2))
        •   “-1”  = Deci (d), (V_S ×️ 10^(-1))
        •    “3”  = Kilo (k), (V_S ×️ 10³)
        •    “6”  = Mega (M), (V_S ×️ 10⁶)
        •    “9”  = Giga (G), (V_S ×️ 10⁹)
        • “12”  = Tera (T), (V_S ×️ 10¹²)
        •   “0”  = Not Applicable (none), (V_S ×️ 10⁰)
        •   “1”  = deca (da), (V_S ×️ 10¹)
        •   “2”  = hecto (h), (V_S ×️ 10²)
      • <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…
                  <linkAtom rel="self" href="ReadingTypeRef"
             …attribute entry of the related <UsagePoint>.
             You can see an example of this use in the “Current Service”, Step 3 XML example, further below.
    • <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
    • <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)

  • 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).

1731128400

2678400

6827000

6827000

  
7251000
2
1733875199
Previous Bill Amount
{SummaryMeasurement}*
3
   
  2678400
  1731128400

  
7251000
2
1733875199
Payment Received On 12/04/24
               Thank You!
{SummaryMeasurement}*
9
   
  2678400
  1731128400

  
5651936
2
1733875199
Current Service
{SummaryMeasurement}*
1
16288
   
  2678400
  1731128400

  
482116
2
1733875199
Environmental Compliance Cost
{SummaryMeasurement}*
4
8530
   
  2678400
  1731128400

  
187986
2
1733875199
Municipal Franchise Fee
{SummaryMeasurement}*
4
3326
   
  2678400
  1731128400

  
505000
2
1733875199
Sales Tax
{SummaryMeasurement}*
5
8000
   
  2678400
  1731128400

840

3

72

347

1733875199

* This is a simplified table.  For {SummaryMeasurement} shown in the “Example-Bill XML Value” column of the above table, see the “UsageSummary - Key Fields” at the top of this page for elaboration of the content of the <SummaryMeasurement> element, which is demonstrated by the XML code example, below.

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 -->


            <!-- 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>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>Payment Received On 12/04/24     Thank You!</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>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>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>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>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>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>

Conclusion

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> that 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 XML structure.

By adopting the Green Button standard, you contribute to a more-interoperable energy ecosystem: empowering better energy management and analytics.  For further guidance and resources, review all of our other Green Button Alliance Developer Resources, using the link, below.