Converting energy units

Use the built-in conversion options

Previously, the API only returned energy data in the Joules unit. As of v3.4 (released 10 Mar 2020) the API supports conversion of units to kWh and kW units, as well as providing an option to calculate power factor directly within the API.

Convert to kWh

To get energy represented as kWh instead of Joules, you can append the ?convert[energy]=kWh query string parameter when calling the following endpoints:

Adding this query string parameter will result in the list of energy data being returned with a modified payload for each interval.

The following properties will not be returned when this parameter is provided:

eReal
eRealPositive
eRealNegative
eReactive
eReactivePositive
eReactiveNegative

These properties will be replaced by:

eRealKwh
eRealPositiveKwh
eRealNegativeKwh
eReactiveKwh
eReactivePositiveKwh
eReactiveNegativeKwh

Note the Kwh suffix for each field.

This query string parameter only affects energy-related properties. All other properties are returned as per a standard API call.

Convert to kW

To get energy represented as kW instead of Joules, you can append the ?convert[energy]=kW query string parameter when calling the following endpoints:

Adding this query string parameter will result in the list of energy data being returned with a modified payload for each interval.

The following properties will not be returned when this parameter is provided:

eReal
eRealPositive
eRealNegative
eReactive
eReactivePositive
eReactiveNegative

These properties will be replaced by:

pRealKw
pRealPositiveKw
pRealNegativeKw
pReactiveKw
pReactivePositiveKw
pReactiveNegativeKw

It's important to note:

the p prefix (rather than e). This is because kW is a measure of power not energy;
the Kw suffix for each field.

This query string parameter only affects energy-related properties. All other properties are returned as per a standard API call.

Calculate power factor

To include power factor in the returned data, you can specify the ?fields[energy]=+pf query string parameter when calling Short and Long energy endpoints:

Unlike the ?convert[energy]=... query string parameters, this will return the standard energy data payload, but will add an additional field to the output:

powerFactor

The powerFactor value is a float between -1 and 1.

The channel needs to be monitoring sufficient current for the power factor value to be meaningful. As a general rule of thumb, a current value of 2% of the CT rating is recommended.

You can safely combine the ?convert[energy]=... query string options with the ?fields[energy]=+pf query string parameter. e.g. ?convert[energy]=kW&fields[energy]=+pf is a valid combination.

However, the ?fields[energy]=+pf query string is not supported for combined phase outputs. i.e. ?filter[group]=phases&fields[energy]=+pf will return an error.

Combined phase

The convert[energy] query string parameter can be combined with phase grouping, with the calculations applying to the grouped values. e.g. the conversion will be calculated on the combined value, rather than the individual phase value.

The fields[energy]=+pf query string parameter is not supported for combined phase. Including both—e.g. ?filter[group]=phases&fields[energy]=+pf will result in an error.

Invalid parameters

Troubleshooting and common "gotchas"

Note that when specifying convert option, the original Joules value is not returned, and the key names are different (as outlined above.)
Combining different convert[energy] values is not supported. e.g. you can't specify ?convert[energy]=kWh,kW—this will result in an error.
Power factor needs to include the + in the query string value. e.g. ?fields[energy]=pf won't work, it must be ?fields[energy]=+pf
You can't combine fields[energy]=timestamp and fields[energy]=+pf. e.g. ?fields[energy]=timestamp,+pf will result in an error.
You can't combine fields[energy]=timestamp and convert[energy]=..., as energy data is not returned when ?fields[energy]=timestamp is specified. Doing so will result in an error.
You can't combine fields[energy]=+pf and filter[group]=phases. Doing so will result in an error.
Conversion of modbus data (exposed via the /modbus API endpoints) using these query string parameters is not supported.

Background

By default, the Wattwatchers API returns energy usage data in Joules, which is a measure of energy. The benefit of returning data 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).

You can now short-cut this by providing query string parameters to the API to do this conversion for you, as per the equations noted below.

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

This information is provided for background benefit, or if for some reason you have to do your own calculations on Joules. We recommend using the query string parameters outlined above instead.

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 the seconds information in 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.)

Calculating power factor

Power factor is calculated according to the following equation in Javascript:

const denominator = Math.sqrt(Math.pow(eReal, 2) + Math.pow(eReactive, 2))
// * 1000 and / 1000 to round to 3 decimals
const powerFactor = denominator != 0 ? Math.round(eReal/denominator * 1000) / 1000 : null

And in python:

denominator: float = math.sqrt(math.pow(e_real, 2) + math.pow(e_reactive, 2))
power_factor: Optional[float] = round(real/denominator, 3) if denominator != 0 else None

Note that you need to first check for zero values for eReal and eReactive so as to avoid device by zero errors.

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:

pRealW[ch] = eReal[ch]/duration

Note that pRealW = "power" (in watts), not energy—i.e. eReal (in Joules).

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