Cost & Currency Representation

The Green Button <currency> field of the ESPI Schema — and by those units: <cost> field — are based on international norms; specifically, the numeric currency representations (“CcyNbr”) found in “List one: Currency, fund and precious metal codes [.xml]” of the ISO 4217:2015 standard.

✏️ — It is important to note that the enumeration within the NAESB REQ.21 ESPI for <currency> contains only thirteen of the ISO 4217 list of roughly 300 currencies but it does include a “0” to denote a currency other than the thirteen enumerated in the Green Button Currency type.

Four common currencies used with Green Button deployments are:

• Canadian Dollar (CAD) = 124
• South Korean Won (KRW) = 410
• United States Dollar (USD) = 840
• European Euro (EUR) = 978

Using the Canadian Dollar as an example, the representation in the context of a <ReadingType> declaration would be as shown on the fifth line:¹

<entry xmlns="http://www.w3.org/2005/Atom">
    … 
    <content>
        <espi:ReadingType>                                              <!-- READING TYPE                  -->
            <espi:accumulationBehaviour>4</espi:accumulationBehaviour>  <!-- incremental interval data     -->
            <espi:commodity>1</espi:commodity>                          <!-- electricity Secondary Metered -->
            <espi:currency>124</espi:currency>  <!-- - - - - - - - - - - - - - - - - Canadian Dollar (CAD) -->
            <espi:dataQualifier>12</espi:dataQualifier>                 <!-- Normal                        -->
            <espi:flowDirection>1</espi:flowDirection>                  <!-- forward                       -->
            <espi:intervalLength>300</espi:intervalLength>              <!-- five minutes                  -->
            <espi:kind>12</espi:kind>                                   <!-- energy                        -->
            <espi:phase>129</espi:phase>                                <!-- Phases A to neutral           -->
            <espi:powerOfTenMultiplier>3</espi:powerOfTenMultiplier>    <!-- 10³                           -->
            <espi:uom>72</espi:uom>                                     <!-- a unit of “Wh”                -->
        </espi:ReadingType>
    </content>
    … 
</entry>

Scaling Factor

The currency field has a predefined scaling factor of “hundred thousandths” of the primary unit of a given currency.

Using the Canadian Dollar as an example, the unit (“dollar”) has two decimal places—what’s known as the “minor unit” in ISO 4217: e.g., $123.45 (where 45 is the minor; a fraction of a full unit called “cents” in this example).

In the above example, there are several elements (also called fields or tags) that we’ll use for other examples, so let’s go into them here:

• <accumulationBehaviour> is set to an enumeration of “4” — which means “incremental interval data”:  “The difference between the value at the end of the prescribed interval and the beginning of the interval. This is used for incremental interval data. Note: One common application would be for load profile data, another use might be to report the number of events within an interval (such as the number of equipment energizations within the specified period of time.)”
• <commodity> is set to an enumeration of “1” — which means “electricity Secondary Metered”:  “All types of metered quantities. This type of reading comes from the meter and represents a ‘secondary’ metered value.”
• <currency> is set to “124” — which refers to the Canadian Dollar and which we are using for these examples on this page.
• <dataQualifier> is set to “12” — which means “Normal”:  “Code describing a salient attribute of Readings of ReadingType.”
• <flowDirection> is set to an enumeration of “1” — which means “forward”:  “‘Delivered,’ or ‘Imported’ as defined 61968-2. Forward Active Energy is a positive kWh value as one would naturally expect to find as energy is supplied by the utility and consumed at the service. Forward Reactive Energy is a positive VArh value as one would naturally expect to find in the presence of inductive loading. In polyphase metering, the forward energy register is incremented when the sum of the phase energies is greater than zero.” (where “61968-2” refers to the IEC 61968-2 System interfaces for distribution management – Part 2: Glossary).
• <intervalLength> is set to a value of “300” — which means 300 seconds for the particular interval measurement (five minutes).  For most residential applications, this value is usually “3600” (one-hour intervals) for electricity readings that are obtained from smart meters.
• <kind> is set to an enumeration of “12” — which refers to a MeasurementKind type of “energy” (since currency, temperature, power factors, and other things could be the measured value instead).
• <phase> is set to an enumeration of “129” — which refers to a PhaseCodeKind type of “AN”:  “Phases A to neutral.”
• <powerOfTenMultiplier> is set to a value of “3” — which you can learn more about on our powerOfTenMultiplier page.
• <uom> (the unit of measure) is set to an enumeration of “72” — which means “Wh”:  “Real energy, Watt hours, Wh.”

EXAMPLE…

If a Data Custodian wanted to denote that an interval of electricity had cost the consumer $3.21 (CAD)² — which is (three dollars and twenty-one cents, Canadian) in a given interval, they would send the following:

<espi:cost>321000</espi:value>      <!-- Three Dollars and Twenty-One Cents, Canadian -->
…
<espi:currency>124</espi:currency>  <!-- Canadian Dollar (CAD) -->

So, using our example, let’s show our formula with a sent <cost> (Cs) of “321000”: 

C = C_S × 10^(-5)   (“hundred thousandths” scaling factor)
C = 321000 × 0.00001   (“three hundred twenty-one thousand  multiplied-by  one hundred-thousandth”)
C = $3.21 CAD   (three dollars and twenty-one cents, Canadian)

The <cost> field is a 48-bit integer, and “3.21” cannot be carried in the <cost> field because it is not an integer.  There can be no decimal in the <cost> field.  The sent cost (C_S) is therefore scaled by 10^(-5) (“hundred thousandths” scaling factor) by the receiver (Third Party or Customer application) to mean “3.21” of the defined currency.

Often, the actual scaled value can be more-or-less verified by understanding the <cost> of the resource (e.g., $ per kWh, m³, litres) and the <intervalLength> but out of context, it may still be difficult to know if the actual scaled value is correct — especially if it still fits within expectations regardless of scaling.  When implementing, as a Data Custodian, it is important to be consistent and:

check the output of real data to be sure you are properly conveying what’s actually desired.

What if the Utility Provides a Power-of-Ten Multiplier for Money?

First of all, for a Line Item represented by <costAdditionalDetailLastPeriod>, the utility (Data Custodian) should not provide a <measurement> for money; it is redundant and the <value> (scaled or not) could potentially conflict with the Line Item <amount>.

✏️ —  If the Data Custodian (utility company) provided a <measurement> and if that contained a multiplier for representing the decimal fields of a currency element, then a Third Party (app developer) should use the provided multiplier rather than the correct C = C_S × 10^(-5) (“hundred thousandths” scaling factor).  The reason for this is to ensure proper representation of the value as intended by the Data Custodian — even if that means the Data Custodian’s output does not meet the Green Button standards.  However, if the scaled-amount and the scaled-value don’t match, the scaled-amount should be used.  See below for more on that topic.

Example:  If a currency value should be C = $3.21 CAD (three dollars and twenty-one cents, Canadian) to be correct, but the raw currency value was <espi:cost>3210</espi:value> and the Data Custodian provided <espi:powerOfTenMultiplier>-3</espi:powerOfTenMultiplier> — being C = C_S × 10^(-3) (“thousandths” scaling factor) — then the provided powerOfTenMultiplier should be used instead of the standard C = C_S × 10^(-5) (“hundred thousandths” scaling factor); otherwise the standard-correct value would be C = $0.0321 CAD (zero dollars, three cents, and twenty-one hundredths of a cent, Canadian) and thus would actually be incorrect for the end-user of the data.  The Third Party needs to always to err on the side of caution: assume the powerOfTenMultiplier (if provided) is to be used — even though it should not be present for currency values. 

What if a Monetary Line Item includes both the Amount and a Measurement — with a Multiplier?

An example of where a <powerOfTenMultiplier> might be found as an override is in a Line Item of <UsageSummary>.  Although a <measurement> should not be used for a monetary Line Item due to unnecessary redundancy and the risk of conflicting values, if a Data Custodian does provide it, the receiver of the data should prioritize the scaled <amount> over the scaled <value> — even if the scaling for <value> is not overridden with a <powerOfTenMultiplier>. 

Below is an example of a Line Item that includes both the <amount> and a <measurement><value> with <powerOfTenMultiplier> scaling override.

✏️ — A note to Data Custodians… do not use this as a template for what to do; it is an example of what not to do as a Data Custodian but rather, how to handle receiving it as a Third Party or end user:

…
    <!-- Line Item: “Sales Tax” = $5.05 = 8% of unrounded $63.125 -->
    <costAdditionalDetailLastPeriod>  <!-- line-item for bill charge -->
        <amount>505000</amount>
        <!-- total for the duration -->
        <!-- <amount> should be used over <value> -->
        <rounding>2</rounding>
        <!-- two places -->
        <dateTime>1733875199</dateTime>
        <note xml:space="preserve">Sales Tax</note>
        <measurement>
            <!-- the <measurement> element and its children should not be present
                 for monetary Line Items; however, if it is provided, then this is
                 an example of what it might contain -->
            <powerOfTenMultiplier>-3</powerOfTenMultiplier>
            <!-- measurement ‘value’ should be represented as hundred-thousandths
                 of the chosen currency; however, the file contains a
                 powerOfTenMultiplier here, so the normal scaling of 10⁽⁻⁵⁾ is
                 being overridden by the powerOfTenMultiplier of “-3” or 10⁽⁻³⁾ -->
            <timeStamp>1733893199</timeStamp>
            <uom>80</uom>
            <!-- unit of measure is “money” -->
            <value>5050</value>
            <!-- value of the summary measurement -->
        </measurement>
        <itemKind>5</itemKind>
        <!-- “Tax” -->
        <unitCost>8000</unitCost>
        <!-- this example tax rate is 8%; thus, 0.08 ÷ 10⁽⁻⁵⁾ = 8000, which is
             using the default, normal scaling of 10⁽⁻⁵⁾ because the <unitCost>
             is outside the <measurement> and thus corresponds to the <amount>,
             itself a monetary reference, and therefore scaled at 10⁽⁻⁵⁾ -->
        <itemPeriod>
            <duration>2678400</duration>
            <start>1731128400</start>
        </itemPeriod>
    </costAdditionalDetailLastPeriod>
…

What if the scaled Amount and scaled Value don’t match?

Short answer:  The <amount> should always be used for a monetary Line Item.

If a Third Party (or end user) receives a file/stream that also has a <measurement> for the monetary Line Item, the scaled <value> may or may not be the same as the scaled <amount> provided:

In the above XML example, the <value>5050</value> is paired with a <powerOfTenMultiplier>-3</powerOfTenMultiplier> — a 10⁽⁻³⁾ multiplier — to produce an actual value of $5.05 (five dollars and five cents).  That scaled-value result matches the <amount>505000</amount> scaled by the correct 10⁽⁻⁵⁾ multiplier. 

If the scaled-value result does not match the scaled-amount result, then a receiver should use the properly scaled-amount result:

That is, the <amount>505000</amount> scaled by the correct 10⁽⁻⁵⁾ multiplier, to be $5.05 rounded by <rounding>.

Additional examples of the Usage Summary and Line Items can be found on our Utility Bill Data mapping page.