Cost & Currency Representation

The Green Button currency field — 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 13 of the ISO 4217 list of roughly 300 currencies but it does include a “0” to denote a currency other than the 13 enumerated in the Green Button Currency type.

Three common currencies used with Green Button deployments are:

• United States Dollar (USD) = "840"
• European Euro (EUR) = "978"
• Canadian Dollar (CAD) = "124"

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

<content>
  <espi:ReadingType>
    <espi:accumulationBehaviour>4</espi:accumulationBehaviour>
    <espi:commodity>1</espi:commodity>
    <espi:currency>124</espi:currency>
    <espi:dataQualifier>12</espi:dataQualifier>
    <espi:flowDirection>1</espi:flowDirection>
    <espi:intervalLength>300</espi:intervalLength>
    <espi:kind>12</espi:kind>
    <espi:phase>129</espi:phase>
    <espi:powerOfTenMultiplier>3</espi:powerOfTenMultiplier>
    <espi:uom>72</espi:uom>
  </espi:ReadingType>
</content>

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 fields/elements/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 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>
...
<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
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 cost field because it is not an integer.  There can be no decimal in the cost field.

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. 

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