Skip to content

API endpoints

Base URL

The following endpoints are available under the API path https://api-v3.wattwatchers.com.au.

e.g. GET /devices should be translated to GET https://api-v3.wattwatchers.com.au/devices.

This URL scheme differs from the v2 API, as noted in Differences between v2 and v3+

Endpoints

GET /devices : List of devices that are authorized for access by the provided API key.

GET /devices/{device-id} : Retrieve status, state and metadata for a specific device (including channels and switches).

PATCH /devices/{device-id} : Update metadata and state for a device (including channels and switches).

GET /devices/channel-categories : List of category definitions that can be applied to device channels.

GET /devices/models : List of valid device models.

GET /short-energy/{device-id} : Short (30 sec) energy data for a specific device and timeframe.

GET /short-energy/{device-id}/first : First short energy data entry received from a specific device.

GET /short-energy/{device-id}/latest : Latest short energy data entry received from a specific device.

GET /long-energy/{device-id} : Long (5 min) energy data for a specific device and timeframe.

GET /long-energy/{device-id}/first : First long energy data entry received from a specific device.

GET /long-energy/{device-id}/latest : Latest long energy data entry received from a specific device.

GET /modbus/{device-id} : Modbus energy data over a specified timeframe for a specific device.

GET /modbus/{device-id}/first : First Modbus energy data entry received from a specific device.

GET /modbus/{device-id}/latest : Latest Modbus energy data entry received from a specific device.

See the Notes and tips section at the end of this document to avoid common pitfalls and points of confusion.

Non-critical whitespace may be included or omitted in requests and responses. They are included in the examples below ("pretty print" style) for clarity of communication only.

GET /devices

Summary

Returns an array of devices that are accessible by the current API key.

Request parameters

None.

Support for skip and limit have been removed from version v3+ of the API. Instead, all device IDs for the given API key will be returned without pagination.

Example request

curl -X GET -H "Authorization: ..." "https://api-v3.wattwatchers.com.au/devices"

Responses

Success

200 OK
[
    "{device-id-1}",
    "{device-id-2}",
    ...
]

GET /devices/{device-id}

Summary

Returns the status and metadata associated with an individual device.

Status information available via the API represents the last known state of this value in the device. This data may be "stale" if the device has not communicated recently to the Wattwatchers system. Be sure to check the latestStatus property.

Request parameters

None.

Example request

curl -X GET -H "Authorization: ..." "https://api-v3.wattwatchers.com.au/devices/D123456789012"

Responses

Success (Cellular devices)

200 OK

{
    "id": "D123456789012",
    "label": "{device-label}",
    "timezone": "{timezone}",
    "model": "6M",
    "firmwareVersion": "{firmware-string}",
    "latestStatus": 1550632148,
    "shortEnergyReportingInterval": 30,
    "pending": {
        "shortEnergyReportingInterval": 5
    },
    "comms": {
        "type": "cellular",
        "mode": "4G",
        "lastHeardAt": 1691035991,
        "signalQualityDbm": -57,
        "simId": "{simId}",
        "apn": "{apn}",
        "imsi": "{imsi}",
        "networkId": "{networkId}"
    },
    "channels": [
        {
            "id": "{channel-id}",
            ...channel-attributes
        }
    ],
    "phases": {
        "count": 3,
        "grouping": ...phase-groups
    },
    "switches": [
        {
            "id": "{switch-id}",
            ...switch-attributes
        }
    ]
}

Tip

Check the model value to determine if the device is modbus capable. The 6M+One model supports modbus.

Success (WiFi devices)

200 OK

{
    "id": "ED12345678901",
    "label": "{device-label}",
    "timezone": "{timezone}",
    "model": "6W",
    "firmwareVersion": "{firmware-string}",
    "latestStatus": 1550684123,
    "shortEnergyReportingInterval": 30,
    "pending": {
        "shortEnergyReportingInterval": 5
    },
    "comms": {
        "type": "wifi",
        "lastHeardAt": 123456789.2341,
        "signalQualityDbm": -57,
        "networkId": "{ssid}"
    },
    "channels": [
        {
            "id": "{channel-id}",
            ...channel-attributes
        }
    ],
    "phases": {
        "count": 3,
        "grouping": ...phase-groups
    },
    "switches": [
        {
            "id": "{switch-id}",
            ...switch-attributes
        }
    ]
}

For Cellular and WiFi devices

  • comms.mode, comms.simId, comms.imsi and comms.apn are only returned for comms.type = cellular—so be sure to check for existence before referencing.
  • comms.networkId for comms.type = cellular is the network (e.g. "Telstra Mobile"); for comms.type = wifi, this is the SSID.
  • comms.signalQualityDbm of 0 indicates unknown value. This will be a negative number otherwise.
  • comms.lastHeardAt is the timestamp of the last known communications from the device to the Wattwatchers system. This can be used as an indicator of a device being "offline", i.e. if older than a pre-defined threshold, as defined by your client application. Note that, unlike energy data, this is a float (equivalent to time.time() in python) with the integer portion = seconds (unix timestamp seconds since epoch). This will return null if the device has never been heard from.
  • comms.mode indicates whether a 4G device is currently connected to a 4G or 3G cellular network (as 4G devices can connect to both technologies).
  • latestStatus is the timestamp of the last received status message from the device, from which the status information is derived.
  • Valid model values are 3M, 6M, 6W, 6M+3SW, 6W+3SW, 6M+One. "Rogowski" devices are identified as 3RM and 3RM+3SW.
  • "phases" returns the phase configuration information relating to the device. For more information on this property, see Phase grouping.
  • label provides a way to identify a device in a context relevant to the user or your business. This might be an asset code, or a description of what room, facility or equipment is being monitored. Note that this property is always returned and defaults to an empty string "" if not set.
  • If one is assigned, timezone represents the timezone that the device is located in. Values are in the TZ database name format—e.g. Australia/Sydney. This allows calling systems to interpret data from the device in the local timezone in which the device resides, without having to track this state in your own system. Note that if no timezone is specified (not set), this property is not returned.

Uninitialised devices

A device that has not connected to the Wattwatchers server (thus in an uninitialised state) will:

  • Include an "uninitialised": true attributed.
  • Not include any latestStatus, comms.lastHeardAt or firmwareVersion values.

Setting channel.ctRating etc. to a non-default value will result in a pending property being returned, as this will only be picked up by the device once it has been initialised and communicated with the Wattwatchers system.

Setting the switch state on an uninitialised device will result a 422 status code being returned.

Fixed in v3.4 Recent versions of the API incorrectly reported uninitialised devices as "Offline".

Reading pending values

When setting writable values within the device (e.g. switch state, CT rating), and you need to confirm the device has taken up the new settings, poll this endpoint (no more frequently than 5 seconds per device) and review the pending values. When the device has responded and accepted the changes, the relevant pending properties will no longer appear in the response.

Channel attributes

For each channel in the channels array:

{
    "id": "D123456789012_C1",
    "ctRating": 60,
    "label": "{user-specified-label}",
    "categoryId": 4,
    "categoryLabel": "Solar",
    "pending": {
        "ctRating": 120
    }
}
  • The categoryLabel is provided as a "shortcut" for client applications for display purposes and reflects the specified categoryId.
  • categoryId must match a value returned by the GET /devices/channel-categories endpoint. A value of -1 represents Not set (and is the default for new devices). A value of 0 represents Not connected.
  • Valid ctRating values are 60A, 120A, 200A, 400A, 600A, 3000A. The 3000A is only applicable to "Rogowski" models (e.g. 3R* device models) and in this circumstance this value is not writable (and therefore will never have a pending value).
  • Metadata information (not stored on the device) = label, categoryId, categoryLabel. Config information (stored on device/affects device operation) = ctRating. Config information has a corresponding "pending" state until the device accepts and reports the change has taken effect.

Phases configuration

When a device is configured to support 3 phase or 2 phase power, using the phases.count property of the device, the phases configuration is returned via the phases.grouping property.

We provide a more detailed explanation of these properties in Phase grouping.

An example collection:

"phases": {
    "count": 3,
    "grouping": [
        {
            "included": [
                "D123456789012_C1",
                "D123456789012_C2",
                "D123456789012_C3"
            ]
        },
        {
            "included": [
                "D123456789012_C4",
                "D123456789012_C5",
                "D123456789012_C6"
            ]
        }
    ]
}

Switch attributes

For each switch in the switches array:

{
    "id": "{switch-id}",
    "state": "open"|"closed",
    "label": "{switch-label}",
    "contactorType": "NO"|"NC",
    "closedStateLabel": "On",
    "openStateLabel": "Off",
    "pending": {
        "state": "open"|"closed"
    }
}
  • The returned data represents the current known state of the switch. This may differ from the actual state if the device has been offline for some time, or physical aspects of the contactor have been modified (e.g. a manual override enabled)
  • label, contactorType, closedStateLabel and openStateLabel are also viewable/editable through the Wattwatchers Onboarding tool
  • pending represents any pending requests for the switch to respond to
  • Metadata information = label, closedStateLabel, openStateLabel. Device config/state information = state.
  • Contactor type can be NO = "Normally Open" or NC = "Normally Closed". This determines how the state values of "open" or "closed" are interpreted to send the correct message to the device.

signalQualityDbm values

signalQualityDbm provides a standard unit of measure (decibels relative to a milliwatt) used to determine the communications signal strength of the device whether it be a cellular or WiFi device.

Typically these are interpreted to provide a "human friendly" signal strength indicator. While the measurement unit is the same, the specific values of what constitutes a "good" signal differ between cellular and WiFi devices.

Such indicators are implementation specific (that is, one party may consider values that are "good" differently to another), however, the following table provides a "rough guide" that you can use to interpret the values returned by the API.

Human-friendly 3G dBm 4G dBm WiFi dBm
Unknown 0 0 0
Excellent -89+ -65+ -40+
Good -95 -75 -55
Low -101 -95 -70
Poor -113 -96 < -70

Values presented are ">=" unless otherwise specified.

Please note that the value exposed by signalQualityDbm reflects the last known signal quality sent by the device, even if the device is currently offline.

PATCH /devices/{device-id}

Summary

Enables updating of a subset of fields for a device and related objects (such as channels and switches).

Request parameters

None.

Request body

{
    "id": "D123456789012",
    "label": "{string, 64}",
    "timezone": "{string, 64}",
    "channels": [
        {
            "id": "D123456789012_C1",
            "label": "{string, 64}",
            "ctRating": 60|120|200|400|600,
            "categoryId": 1
        }
    ],
    "phases": {
        "count": 3,
        "grouping": [
            {
                "included": [
                    "D123456789012_C1",
                    "D123456789012_C2",
                    "D123456789012_C3"
                ]
            },
            {
                "included": [
                    "D123456789012_C4",
                    "D123456789012_C5",
                    "D123456789012_C6"
                ]
            }
        ]
    },
    "switches": [
        {
            "id": "D123456789012_S3",
            "label": "{string, 64}",
            "state": "open"|"closed",
            "contactorType": "NO"|"NC",
            "closedStateLabel": "{string, 16}",
            "openStateLabel": "{string, 16}"
        }
    ]
}
  • The example request body above shows all of the writable properties, and related values or string lengths.
  • To avoid ambiguity with channel or switch IDs implied by their order in the relevant array, the id property must be specified for channels and switches.
  • Writable values are dependent on permissions assigned to the API key. Attempting to set these when the API key is not authorised to do so will return a 403 FORBIDDEN status.
  • The channel.ctRating should be specified to match the physical installation (i.e. the API cannot detect if the specified value does not match).
  • channel.ctRating cannot be set for Rogowski (3R) devices. By design this cannot be changed from 3000.
  • channel.categoryId can be set to match the ID for the categories reported by the GET /devices/channel-categories endpoint. Note that channel.categoryLabel returned in the GET /devices/{device-id} endpoint is read only and cannot be set using the PATCH method.
  • Valid values for switch.contactorType are NO (normally open) and NC (normally closed).
  • switch.closedStateLabel and switch.openStateLabel are short as these will appear in user interfaces. For example, they should be something like "On" or "Off", or "Enabled", "Disabled" etc.
  • See Phase grouping for more information on the phases object.
  • Note that shortEnergyReportingInterval is a read-only setting. While it is returned in the GET devices/{device-id} payload, it will return a 403 Not Permitted if you attempt to change this value.
  • New in v3.5 A device-level label can be assigned for display or identification purposes. It helps the user or calling system identify the device. It is displayed in the Dashboard portal and billing invoices as a descriptor for the device. The label should be a string, maximum 64 characters long. Passing an empty string "" or a null value will remove the current label.
  • New in v3.5 timezone is a string representing a TZ database name. For example, to specify a device is in the timezone of Auckland, New Zealand, you would specify Pacific/Auckland. This information helps giving more context to the energy data. For example, it allows displaying the energy data in the device's local time, without having to store this state in an external system.

Writing pending values

Setting the following fieldswill return a 202 Accepted HTTP status code, and the result payload will list them as "pending":

  • channel.ctRating
  • switch.state

This is because the changes requested need to be "picked up" and applied on the device, which may take some time. See Reading pending values above for more information.

State value and labels

A switch may be in either an open or closed state. The "meaning" of this state in user-friendly terms may differ depending on the installation.

The device needs to know whether the contactor type (that performs the switching action) is "normally open" or "normally closed" in order to be able to interpret the meaining of the state value.

While in a typical installation, open equates to "Off", and closed to "On", in some circumstances a closed switch may trigger another circuit to turn a device off (flipping the typical behaviour).

The openStateLabel and closedStateLabel values provide a user-friendly representation of the related state value, defaulting to "on" for closed and "off" for open.

Unitialised devices

A device that has not yet communicated with Wattwatchers' servers (thus in an uninitialised state) will still allow setting of values.

In this case, "pending" values will not be displayed/returned, as there is no actual device state to reference.

If you submit multiple config requests prior to the device coming online, these will be queued and replayed to the device in the sequence they were recorded when the device starts communicating. Thus it may take some time before the device reflects the desired end state after start-up if there are multiple messages queued at the time of initialisation.

Attempting to set the switch state for an uninitialised device will return a 422 Unprocessable Entity response code. No other warnings or errors will be issued when setting values for uninitialised devices.

Responses

Success

200 OK
{
    "status": 200,
    "result": {
        ...as per GET request, echoing the updated state (with switch state pending)
    }
}

422 Unprocessable Entity

This code will be returned if:

  • an id value for a channel or switch is provided that doesn't match the device ID in the URL or request body;
  • a channel or switch ID is provided that could not be found (e.g. specifying a value for channel 4 on a 3 channel device);
  • a ctRating other than 3000 is provided for a Rogowski device (as the CT rating is fixed at 3000A for these devices);
  • an unaccepted value is specified in the request body (e.g. a value other than "open" or "closed" specified for switch state), in accordance with our conventions;
  • an attempt to set the switch state for an uninitialised device is made.

403 Not Permitted

This code will be returned if you attempt to set the shortEnergyReportingInterval value.

GET /devices/channel-categories

Summary

Returns an array of category definitions that can be applied to any given device channel.

Request parameters

None.

Example request

curl -X GET -H "Authorization: ..." "https://api-v3.wattwatchers.com.au/devices/channel-categories"

Responses

Success

200 OK
[
    {
        "id": -1,
        "label": "Not set",
        "description": "No category has been set for this channel."
    },
    {
        "id": 0,
        "label": "Not connected",
        "description": "The channel is available on the device, but is not connected to a circuit."
    },
    ...etc.
]
  • This provides client applications with a list of valid options to present via user interfaces or for validation purposes.
  • description provides guidance as to the intended application of the category.
  • id can be used in the PATCH /devices/{device-id} endpoint for channel.categoryId

GET /devices/models

Summary

Returns a list of valid device models.

Request parameters

None.

Example request

curl -X GET -H "Authorization: ..." "https://api-v3.wattwatchers.com.au/devices/models"

Responses

Success

200  OK
[
    {
        "code": "3M",
        "displayName": "Auditor 3M",
        "channelsCount": 3,
        "switchesCount": 0,
        "communications": "cellular"
    },
    ...
]

Tip

To determine if a device model is modbus capable, check the code includes +One (the 6M+One model supports modbus).

GET /short-energy/{device-id}

Summary

Returns short energy data for a specific device. Typically this is every 30 seconds, but depends on the shortEnergyReportingInterval setting of the device. Note that the duration may change if the shortEnergyReportingInterval on the device is changed in the time period being requested.

Due to the nature of how short energy is reported by devices, there may be gaps in data returned by this API call.

If a device has lost communication with the Wattwatchers system (even temporarily) this API call may return an empty list (representing no data available for the specified period).

Short energy is currently available via the API for up to 31 days. If you require a longer-term archive, you will need to retrieve and store in your own systems.

Request parameters

Param name Format Required Notes
fromTs Integer N Unix timestamp, seconds since epoch. Returns data with timestamp >= fromTs. Default, if not specified: now minus 1 hour.
toTs Integer N Unix timestamp, seconds since epoch. Returns data with timestamp < toTs. Default, if not specified: 1 hour after fromTs.
filter[group] Enum (String) N New in v3.1 When present, and set to phases (currently the only supported value), the energy data entries will be collapsed to reflect the phases.grouping configuration of the device. More information in Phase grouping
convert[energy] Enum (String) N New in v3.4 Valid values: kWh or kW. Converts energy data to kilowatt hours or kilowatts. See Converting energy units for more information on usage.
fields[energy] Enum (String) N New in v3.4 Valid values: +pf. fields[energy]=+pf will append calculated power factor to the returned energy data objects. See Converting energy units for more information on usage. Note that filter[group]=phases can't be combined with fields[energy]=+pf.

The maximum time period (between fromTs and toTs) per request is 12 hours.

Example request

Specifying fromTs only (returns 1 hour of data or until the current time, whichever is sooner):

curl -X GET -H "Authorization..." "https://api-v3.wattwatchers.com.au/short-energy/D123456789012?fromTs=1550625612"

Responses

Success

Example from a 3 channel device:

200 OK
[
    {
        "timestamp": 1550622130,
        "duration": 30,
        "frequency": 50.04,
        "eReal": [
            1150, 2, 38
        ],
        "eReactive": [
            -857, -19, -364
        ],
        "vRMS": [
            244.9, 244.8, 244.8
        ],
        "iRMS": [
            1.259, 0.028, 0.31
        ]
    },
    {
        "timestamp": 1550622135,
        "duration": 30,
        "frequency": 50.04,
        "eReal": [
            1142, 3, 39
        ],
        "eReactive": [
            -857, -19, -364
        ],
        "vRMS": [
            244.3, 244.2, 244.3
        ],
        "iRMS": [
            1.252, 0.028, 0.309
        ]
    },
    ...
]
  • Results are returned ordered from earliest timestamp to latest.
  • duration will match the shortEnergyReportingInterval that was set on the device at the time of the reading, and thus may differ between entries if this value has changed on the device during the time period retrieved/specified.

Period > 12 hours

422 Unprocessable Entity
{
    "code": "UNPROCESSABLE_ENTITY",
    "httpCode": 422,
    "message": "The requested time period is greater than 12 hours."
}

Other error responses

See also: Common error responses

GET /short-energy/{device-id}/first

Summary

Returns the first received short energy entry from the device.

Request parameters

Param name Format Required Notes
filter[group] Enum (String) N New in v3.2 When present, and set to phases (currently the only supported value), the energy data entries will be collapsed to reflect the phases.grouping configuration of the device. More information in Phase grouping
convert[energy] Enum (String) N New in v3.4 Valid values: kWh or kW. Converts energy data to kilowatt hours or kilowatts. See Converting energy units for more information on usage.
fields[energy] Enum (String) N New in v3.4 Valid values: +pf or timestamp. fields[energy]=+pf will append calculated power factor to the returned energy data objects. See Converting energy units for more information on usage. timestamp will return just the timestamp attribute in the returned data object. +pf and timestamp are mutually exclusive and can't be combined—i.e. fields[energy]=+pf,timestamp will result in an error. The fields[energy] query string options can't be combined with filter[group]=phases.

Responses

Success

As per general short energy requests, but rather than a list of entries, it just returns a single energy object.

Note that the variations for phase grouping are also reflected in this return value.

200 OK
{
    "timestamp": 1550622145,
    "duration": 5,
    "frequency": 50,
    "eReal": [
        1163, 3, 39
    ],
    "eReactive": [
        -856, -19, -363
    ],
    "vRMS": [
        244.6, 244.5, 244.5
    ],
    "iRMS": [
        1.267, 0.028, 0.309
    ]
}

With the fields[energy]=timestamp query string parameter, the returned value will look like:

200 OK
{
    "timestamp": 1550622145
}

Error responses

See also: Common error responses

GET /short-energy/{device-id}/latest

Summary

Returns the latest received short energy entry from the device.

latest endpoints are provided to assist in determining the latest timestamp when it is not already known/tracked by your system. The query may take some time to complete. A query for a specific fromTs will be more performant.

Request parameters

Param name Format Required Notes
filter[group] Enum (String) N New in v3.2 When present, and set to phases (currently the only supported value), the energy data entries will be collapsed to reflect the phases.grouping configuration of the device. More information in Phase grouping
convert[energy] Enum (String) N New in v3.4 Valid values: kWh or kW. Converts energy data to kilowatt hours or kilowatts. See Converting energy units for more information on usage.
fields[energy] Enum (String) N New in v3.4 Valid values: +pf or timestamp. fields[energy]=+pf will append calculated power factor to the returned energy data objects. See Converting energy units for more information on usage. timestamp will return just the timestamp attribute in the returned data object. +pf and timestamp are mutually exclusive and can't be combined—i.e. fields[energy]=+pf,timestamp will result in an error. The fields[energy] query string options can't be combined with filter[group]=phases.

Responses

Success

As per /short-energy/{device-id}/first.

Error responses

See also: Common error responses

GET /long-energy/{device-id}

Summary

Returns the energy data for a single device.

All long energy reported by a device is currently available via the API (with no retention limits). We may introduce data archiving for old data in the future.

At launch (in Feb 2019) the Mercury API only provides access to data from 1 Jan 2019. Please contact the Wattwatchers team to discuss your requirements and timings for full device data history.

Request parameters

Param name Format Required Notes
fromTs Integer N Unix timestamp, seconds since epoch. Returns data with timestamp >= fromTs. Default, if not specified: first long energy entry.
toTs Integer N Unix timestamp, seconds since epoch. Returns data with timestamp < toTs. Default, if not specified: 7 days after fromTs.
granularity String N Valid values: 5m, 15m, 30m, hour, day, week, month. Default, if not specified: 5m.
timezone String N Required if granularity = hour or greater. Ignored if granularity is another value. Valid values: outlined here. Default, if not specified = Australia/Sydney
filter[group] Enum (String) N New in v3.2 When present, and set to phases (currently the only supported value), the energy data entries will be collapsed to reflect the phases.grouping configuration of the device. More information in Phase grouping
convert[energy] Enum (String) N New in v3.4 Valid values: kWh or kW. Converts energy data to kilowatt hours or kilowatts. See Converting energy units for more information on usage.
fields[energy] Enum (String) N New in v3.4 Valid values: +pf. fields[energy]=+pf will append calculated power factor to the returned energy data objects. See Converting energy units for more information on usage. Note that filter[group]=phases can't be combined with fields[energy]=+pf.

The maximum time period (between fromTs and toTs) per request is dependent on the granularity:

Granularity Max. time period
5m 7 days
15m 14 days
30m 31 days
hour 3 months
day 3 years
week 5 years
month 10 years

See Differences between v2 and v3+ for details of how fromTs and toTs are interpreted, and how they differ from the v2 API.

See fromTs, toTs and granularity boundaries for details of how fromTs or toTs timestamps that do not match the granularity boundary are handled.

Example request

With 15m granularity:

curl -X GET -H "Authorization..." "https://api-v3.wattwatchers.com.au/long-energy/D123456789012?fromTs=1550408400&granularity=15m"

With parameters specified:

curl -X GET -H "Authorization..." "https://api-v3.wattwatchers.com.au/long-energy/D123456789012?fromTs=1550408400&toTs=1550580600&granularity=hour&timezone=Pacific/Auckland"

Responses

Success

Example for 6 channel device with 15m granularity:

[
    {
        "timestamp": 1550408400,
        "duration": 900,
        "eReal": [
            3639405, 336898, -560, 37, -14, -25
        ],
        "eRealNegative": [
            0, 0, 560, 0, 14, 25
        ],
        "eRealPositive": [
            3639405, 336898, 0, 37, 0, 0
        ],
        "eReactive": [
            154581, 140216, 61, 45, -4, 11
        ],
        "eReactiveNegative": [
            13832, 0, 0, 0, 5, 0
        ],
        "eReactivePositive": [
            168413, 140216, 61, 45, 1, 11
        ],
        "vRMSMin": [
            229.4, 229.5, 229.6, 229.4, 229.5, 229.6
        ],
        "vRMSMax": [
            232.2, 232.4, 232.4, 232.2, 232.4, 232.5
        ],
        "iRMSMin": [
            14.799, 0.331, 0.023, 0.023, 0.023, 0.022
        ],
        "iRMSMax": [
            21.208, 4.534, 0.043, 0.046, 0.043, 0.042
        ]
    },
    {
        "timestamp": 1550409300,
        "duration": 900,
        "eReal": [
            3424152, 179654, -515, 46, -11, -19
        ],
        "eRealNegative": [
            0, 0, 515, 0, 11, 19
        ],
        "eRealPositive": [
            3424152, 179654, 0, 46, 0, 0
        ],
        "eReactive": [
            53228, 93184, 65, 36, -7, 10
        ],
        "eReactiveNegative": [
            21765, 0, 0, 0, 8, 0
        ],
        "eReactivePositive": [
            74993, 93184, 65, 36, 1, 10
        ],
        "vRMSMin": [
            229.4, 229.5, 229.6, 229.4, 229.5, 229.6
        ],
        "vRMSMax": [
            231.4, 231.5, 231.6, 231.4, 231.6, 231.7
        ],
        "iRMSMin": [
            15.574, 0.329, 0.023, 0.022, 0.023, 0.023
        ],
        "iRMSMax": [
            19.933, 4.147, 0.026, 0.025, 0.025, 0.025
        ]
    },
    ...
]

The details of units for the values returned our outlined in Energy units.

Period > valid values for granularity

The valid number of days that can be returned in a given long energy API call will depend on the granularity. In the event that an invalid time period is specified, a 422 will be returned. e.g.

422 Unprocessable Entity
{
    "code": "UNPROCESSABLE_ENTITY",
    "httpCode": 422,
    "message": "The requested time period is greater than 7 days."
}

Timezone not specified

If timezone not specified when a granularity parameter of hour or greater is specified.

400 Bad Request
{
    "code": "BAD_REQUEST",
    "httpCode": 400,
    "message": "You must specify a valid timezone value when applying granularity of 'hour', 'day', 'week', or 'month.'"
}

Other error responses

See also: Common error responses

GET /long-energy/{device-id}/first

Summary

Returns the first received long energy entry from the device.

Request parameters

Param name Format Required Notes
filter[group] Enum (String) N New in v3.2 When present, and set to phases (currently the only supported value), the energy data entries will be collapsed to reflect the phases.grouping configuration of the device. More information in Phase grouping
convert[energy] Enum (String) N New in v3.4 Valid values: kWh or kW. Converts energy data to kilowatt hours or kilowatts. See Converting energy units for more information on usage.
fields[energy] Enum (String) N New in v3.4 Valid values: +pf or timestamp. fields[energy]=+pf will append calculated power factor to the returned energy data objects. See Converting energy units for more information on usage. timestamp will return just the timestamp attribute in the returned data object. +pf and timestamp are mutually exclusive and can't be combined—i.e. fields[energy]=+pf,timestamp will result in an error. The fields[energy] query string options can't be combined with filter[group]=phases.

Responses

Success

As per general long energy requests, but rather than a list of entries, it just returns a single energy object.

Note that the variations for phase grouping are also reflected in this return value.

200 OK
{
    "timestamp": 1550410200,
    "duration": 900,
    "eReal": [
        3586031, 329486, -549, 39, -13, -24
    ],
    "eRealNegative": [
        0, 0, 549, 0, 13, 24
    ],
    "eRealPositive": [
        3586031, 329486, 0, 39, 0, 0
    ],
    "eReactive": [
        134087, 136446, 47, 33, -10, 11
    ],
    "eReactiveNegative": [
        11739, 0, 0, 0, 10, 0
    ],
    "eReactivePositive": [
        145826, 136446, 47, 33, 0, 11
    ],
    "vRMSMin": [
        228.6, 228.8, 228.8, 228.6, 228.8, 228.9
    ],
    "vRMSMax": [
        231.8, 232, 232, 231.8, 232, 232.1
    ],
    "iRMSMin": [
        15.473, 0.332, 0.023, 0.023, 0.023, 0.023
    ],
    "iRMSMax": [
        21.451, 4.539, 0.035, 0.038, 0.04, 0.04
    ]
}

Error responses

See also: Common error responses

GET /long-energy/{device-id}/latest

Summary

Returns the latest received long energy entry from the device.

latest endpoints are provided to assist in determining the latest timestamp when it is not already known/tracked by your system. The query may take some time to complete. A query for a specific fromTs will be more performant.

Request parameters

Param name Format Required Notes
filter[group] Enum (String) N New in v3.2 When present, and set to phases (currently the only supported value), the energy data entries will be collapsed to reflect the phases.grouping configuration of the device. More information in Phase grouping
convert[energy] Enum (String) N New in v3.4 Valid values: kWh or kW. Converts energy data to kilowatt hours or kilowatts. See Converting energy units for more information on usage.
fields[energy] Enum (String) N New in v3.4 Valid values: +pf or timestamp. fields[energy]=+pf will append calculated power factor to the returned energy data objects. See Converting energy units for more information on usage. timestamp will return just the timestamp attribute in the returned data object. +pf and timestamp are mutually exclusive and can't be combined—i.e. fields[energy]=+pf,timestamp will result in an error. The fields[energy] query string options can't be combined with filter[group]=phases.

Responses

Success

As per /long-energy/{device-id}/first.

Error responses

See also: Common error responses

GET /modbus/{device-id}

Summary

Returns the modbus energy data for a specific device.

Request parameters

Param name Format Required Notes
fromTs Integer N Unix timestamp, seconds since epoch. Returns data with timestamp >= fromTs. Default
toTs Integer N Unix timestamp, seconds since epoch. Returns data with timestamp < toTs. Default (if not provided) = 7 days after fromTs.

The maximum time period (between fromTs and toTs) per request is 7 days.

As modbus devices report cumulative (rather than interval) data, granularity is not applicable.

Responses

Success

The following example illustrates a multi-entry payload, where each entry is from the two currently supported modbus devices, the CETA PMC-220 (single phase) and PMC-340B (3 phase) meters.

See the Modbus data fields documentation for more information on the data returned by modbus devices, including the units provided.

[
  {
    "_Ia": 0.0,
    "_Ib": 0.0,
    "_Ic": 0.0,
    "_PFa": 1.0,
    "_PFb": 1.0,
    "_PFc": 1.0,
    "_Uan": 244.8056182861328,
    "_Ubn": 122.43417358398438,
    "_Ucn": 122.45341491699219,
    "kVAh": 0,
    "kWh_Exp": 0,
    "kWh_Imp": 0,
    "kWh_Net": 0,
    "kWh_Tot": 0,
    "kvarh_Q1": 0,
    "kvarh_Q2": 0,
    "kvarh_Q3": 0,
    "kvarh_Q4": 0,
    "kvarh_Exp": 0,
    "kvarh_Imp": 0,
    "kvarh_Net": 0,
    "kvarh_Tot": 0,
    "model": "PMC-340B",
    "timestamp": 1546952400
  },
  {
    "_I": 0.3065536916255951,
    "_V": 245.0169219970703,
    "_PF": 0.5856215357780457,
    "kVAh": 616,
    "kWh_Exp": 0,
    "kWh_Imp": 283,
    "kWh_Net": 283,
    "kWh_Tot": 283,
    "kvarh_Exp": 173,
    "kvarh_Imp": 0,
    "kvarh_Net": -173,
    "kvarh_Tot": 173,
    "model": "PMC-220",
    "timestamp": 1546956000
  }
]

The data entries match the format of the source data, with timestamp and model included in each packet. The model and related payload may change over time if the attached modbus meter is changed.

Note that duration isn't included in modbus data as these are total energy meters (cumulative) not interval data, therefore duration is not relevant.

Period > 7 days

The valid number of days that can be returned for modbus data is 7 days. In the event that an invalid time period is specified, a 422 will be returned. e.g.:

422 Unprocessable Entity
{
    "code": "UNPROCESSABLE_ENTITY",
    "httpCode": 422,
    "message": "The requested time period is greater than 7 days."
}

No data for period

If the device has registered modbus data associated with it, but no data is available for the specified period, an empty list is returned:

200 OK
[]

No data for device

If no modbus data has been received from the device, or the device is not a modbus-capable device, a 204 No Content response will be returned.

Non-modbus device

If you attempt to request modbus data (using the /modbus/{device-id} endpoint) for a device that doesn't support modbus data, you will get a 422 Unprocessable Entity status response:

{
    "code": "UNPROCESSABLE ENTITY",
    "httpCode": 422,
    "message": "You have attempted to query modbus data for a device ID that does not support it"
}

Other error responses

See also: Common error responses

GET /modbus/{device-id}/first

Summary

Returns the first recorded modbus energy data entry for a specific device.

Request parameters

Param name Format Required Notes
fields[energy] Enum (String) N New in v3.4 Valid values: timestamp. fields[energy]=timestamp will return just the timestamp attribute in the returned data object.

Responses

Success

As per the GET /modbus/{device-id} payload, except not in a list. The example below shows data for the PMC-340B.

See the Modbus data fields documentation for more information on the data returned by modbus devices, including the units provided.

{
  "_Ia": 0.0,
  "_Ib": 0.0,
  "_Ic": 0.0,
  "_PFa": 1.0,
  "_PFb": 1.0,
  "_PFc": 1.0,
  "_Uan": 244.8056182861328,
  "_Ubn": 122.43417358398438,
  "_Ucn": 122.45341491699219,
  "kVAh": 0,
  "kWh_Exp": 0,
  "kWh_Imp": 0,
  "kWh_Net": 0,
  "kWh_Tot": 0,
  "kvarh_Q1": 0,
  "kvarh_Q2": 0,
  "kvarh_Q3": 0,
  "kvarh_Q4": 0,
  "kvarh_Exp": 0,
  "kvarh_Imp": 0,
  "kvarh_Net": 0,
  "kvarh_Tot": 0,
  "model": "PMC-340B",
  "timestamp": 1546952400
}

Error responses

See also: Common error responses

GET /modbus/{device-id}/latest

Summary

Returns the most recent recorded modbus energy data entry for a specific device.

latest endpoints are provided to assist in determining the latest timestamp when it is not already known/tracked by your system. The query may take some time to complete. A query for a specific fromTs will be more performant.

Request parameters

Param name Format Required Notes
fields[energy] Enum (String) N New in v3.4 Valid values: timestamp. fields[energy]=timestamp will return just the timestamp attribute in the returned data object.

Responses

Success

As per GET /modbus/{device-id}/first.

Error responses

See also: Common error responses

Notes and tips

Trailing slashes

Endpoints do not have trailing slashes (e.g. https://api-v3.wattwatchers.com.au/devices not https://api-v3.wattwatchers.com.au/devices/). Providing the trailing slash will result in errors.

URL and query string parameters are case sensitive

Ensure that your query string parameters match the case specified in the documentation. The API does not recognise alternative case (e.g. fromts or ToTS etc. will revert to defaults.)

Similarly /Devices/D123456789012 will result in a 404 response.

Timestamps

Timestamps represent the END of the data collection period

Timestamps represent the end of period if data collected by the device. This is the same as v2 API behaviour, but is restated here for clarity.

For example, if you request data with a fromTs of 11:50am with a 5m granularity, the first entry will represent data logged by the device between 11:45:01 and 11:50:00. Similarly, specifying 12:00am with a day granularity will result in data from the previous day being returned.

Timestamps are integers

All timestamps are Unix Epoch "seconds since 1970" timestamps.

Non-integer values will result in a 400 Bad Request response.

Javascript developers, this is different to the millisecond variation produced by new Date().getTime(). Use parseInt(new Date().getTime()/1000) to get the seconds value.

fromTs, toTs and granularity boundaries

Both v2 and v3 return partial data if a fromTs or toTs timestamp is provide that does not fall on the granularity boundary. e.g. if a fromTs of 10:05am was specified with a 15m granularity, the first entry would only contain 25 minute's worth of data (5m data received between the fromTs of 10:05am and 10:15am (the end of the corresponding 15 min period)).

The same principle applies to toTs values. e.g. if a fromTs of 10:00am and toTs of 10:55am was specified, only data up to 10:55am would be returned.

In both cases, the duration value of the relevant energy data point will be smaller than the specified granularity value (e.g. the duration would be 600 instead of the usual 900 in both examples above.)

fromTs and toTs scope

fromTs={timestamp} will return data with timestamp >= fromTs.

toTs={timestamp} will return data with timestamp < toTs.

Singular vs. plural names

Collection endpoints use the plural name of the entity and individual entities are accessible under this URL for consistency and simplicity (e.g. /devices + /devices/D123456789012 not /devices + /device/D123456789012)

Energy units

The following units of measurement are used across all energy calls. See also: Concepts.

Physical Quantity Fields Data Type Unit of Measurement
Real Energy eReal, eRealPositive, eRealNegative Integer J (Joules)
Reactive Energy eReactive, eReactivePositive, eReactiveNegative Integer J (Joules)
Voltage vRMS, vRMSMin, vRMSMax Float V (Volts)
Current iRMS, iRMSMin, iRMSMax Float A (Amperes)
Frequency frequency Float Hz (Hertz)
Duration duration Integer Seconds
Timestamp timestamp Integer Unit timestamp, seconds since Epoch (1 Jan 1970)

Energy data from misconfigured devices

If a device is configured incorrectly (e.g. the incorrect CT rating is specified), the device will record invalid data.

The API reports data as it was recorded by the device, and does not make "corrections" on the way out in reference to misconfiguration.

Configuration changes not timestamped

We do not track changes to device properties (whether they be device-related such as CT rating, or metadata such as channel labels) as timeseries data.

Thus there is no way, presently via the API, to query what the device settings were at a particular point and time, and changes to metadata are assumed to apply for the full device history.

e.g. if a device is initially configured to monitor Solar generation, and then is reconfigured to record data from a Battery, the change of label and labelCategory are considered to apply to the entire device history.

If you need to support this use case, you will need to track the time of such changes and apply these within your own systems/integration/implementation.

Changing CT ratings quickly back and forth

Note that CT rating changes take some time to be picked up by the device.

If you change a CT rating (say, from 60A to 120A) a "pending" attribute will be added, and a message queued for the device to update its configuration.

If you change the CT rating back (e.g. 120A to 60A) before the device has picked up the queued configuration change, the "pending" attribute will be temporarily discarded (as the device and the requested state currently match). When the device picks up the next round of messages, there may be a temporary period where the device returns into "pending" mode when the device responds to the original 120A config change request, but the second restoring message has not yet been picked up.

To avoid this issue, we recommend designing your system to wait until the "pending" value is cleared (i.e. the device has changed its configuration to match the intended state) before issuing a new CT rating change request.

Get started quickly with our OpenAPI specification

Learn more about how to get started with our API quickly using the OpenAPI specification