Cost & Currency Representation
espi:cost & espi:currency
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 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:1
<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 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 aMeasurementKind
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 aPhaseCodeKind
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)
2 — 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 = CS × 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 incost
field because it is not an integer. There can be no decimal in thecost
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.
- ^ See the page on Atom & ESPI to understand the “
espi:
” notation herein.
- ^ Because “thousands” and “decimal” placeholders vary in different countries and regions, please note that the examples here use your browser’s LOCALE information to format the example results into a locale-specific representation of numbers. Therefore, in our examples that use a comma for marking thousands and a period (full-stop character) for marking decimals (like this: $9,876.54321), you may see
$9876.54321
— which isnine thousand eight hundred seventy-six and fifty-four thousand three hundred twenty-one hundred-thousandths
in any case.