# Converting energy units

Documentation for the Wattwatchers API

V1.0.4 last updated 2 months ago on 2019/08/19

The Wattwatchers API returns energy usage data in Joules, which is a measure of energy. The benefit of providing data at in Joules is that it provides a fine level of granularity without conversion factors relating to decimal/floats which can be an issue when translating between systems.

Many of us are more familiar with measures like kilowatt hours (kWh), or need to convert energy values into a representation of power e.g. kilowatts (kW). Also, we often need to translate data coming out of the Wattwatchers API for input into, or comparison with data from, other systems that track energy as kWh, or represent loads as kW.

Thankfully, Joules can be converted into other units quite easily. This support note outlines the equations for converting the data provided by the API into the two units mentioned above—kWh (energy) and kW (power).

We'll demonstrate in two common programming languages, Javascript and python.

## Convert Joules to Kilowatt hours

In both examples, the datapoint from the API that we're demonstrating with is `eReal`

. However, this same principle applies to any value returned from the API as Joules.

Both Joules (J) and kilowatt hours (kWh) are measures of energy over time.

As such, the equation for converting between the two is quite straightforward.

`1 Joule = (1/3600000)kWh`

Once you have the `eReal`

value, you multiply it by the conversion factor noted above. For example, in Javascript:

```
const jToKwh = (1/3600000); // or you could express as a float: 0.000000277777778
let eRealJ = 1;
let eRealKwh = eRealJ * jToKwh;
```

And in python:

```
j_to_kwh: float = 0.000000277777778 # this is 1/3600000 as a float
e_real_j: int = 1
e_real_kwh: float = e_real_j * j_to_kwh
```

## Convert Joules to Kilowatts

The equation for conversion is, again, quite straightforward:

`kW = J / (1000 × seconds)`

Unlike the conversion to kilowatt hours, kilowatts are a measure of power at any one point in time.

Thus, in order to do this conversion, you also need to know the time period that the original Joules value was measured across (`seconds`

in the above equation.)

The API returns this information via the `duration`

property for both Short and Long Energy (this does not apply to modbus data, which is cumulative and thus does not include a duration property.)

In Javascript, for a 5 min duration, this translates to:

```
const duration = 300; // 5 minute period = 5 * 60 = 300
let eRealJ = 1;
let eRealKw = eRealJ / (1000 * duration)
```

In python, for a 15 min duration:

```
duration: int = 900 # 15 minute period = 15 * 60 = 900
e_real_j: int = 1
e_real_kw: float = e_real_j) / (1000.0 * duration) # 1000.0 ensures result is floating point number in python 2
```

**Reminder:** As noted earlier, you can apply these same calculations to any of the energy values returned the API as Joules (for example `eRealPositive`

or `eRealNegative`

.)

## Power, RMS Voltage and Current

The Short Energy readings include duration (`duration`

), real energy (`eReal`

), RMS current (`iRMS`

) and RMS voltage (`vRMS`

).

The equivalent real power over the measurement interval can be calculated for each channel:

`pReal[ch] = eReal[ch] / duration`

`vRMS`

and `iRMS`

readings are calculated from the last 5 mains cycles at the end of the measurement interval. Because `vRMS`

and `iRMS`

will usually vary over the measurement interval, and the current and voltage will not usually be exactly in phase, the product of `vRMS`

and `iRMS`

will **not** usually equate to `pReal`

.

Voltage and current together are not intended to be used to estimate energy: energy is evaluated using completely different methods based on continuous sampling at high frequency.

So what are `vRMS`

and `iRMS`

useful for? There are a number of applications that are interested in `vRMS`

and `iRMS`

, particularly the minimum and maximum values provided in Long Energy. For example:

- If grid voltage goes high, even for a moment, then inverters are required to stop feeding in current to the grid
- Distributors have obligations to manage voltage
- Distributors are interested in transformer loads independent of voltage and power factor i.e. currents
- Short Energy current is a good way to see what is actually happening where many loads are connected
- High average voltage is a bad thing for many loads, even when they don’t use much current or energy