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",
    "model": "3M",
    "firmwareVersion": "{firmware-string}",
    "latestStatus": 1550632148,
    "shortEnergyReportingInterval": 30,
    "pending": {
        "shortEnergyReportingInterval": 5
    },
    "comms": {
        "type": "cellular",
        "lastHeardAt": 123456789.2341,
        "signalQualityDbm": -57,
        "networkId": "{networkId}",
        "apn": "{apn}",
        "simId": "{simId}",
        "imsi": "{imsi}"
    },
    "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": "D123456789012",
    "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.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.
  • 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.
  • New in v3.2: "phases" returns the phase configuration information relating to the device. For more information on this property, see Phase grouping.

Uninitialised devices

New in v3.1: 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.

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

New in v3.2: 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-friendly3G dBm4G dBmWiFi dBm
Unknown000
Excellent-89+-65+-40+
Good-95-75-55
Low-101-95-70
Poor-101-96< -70
No signal<= -110<= -95...

Values presented are ">=" unless otherwise specified.


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",
    "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.
  • New in v3.1: 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.

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 present, but not connected to a circuit on this device"
    },
    ...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 nameFormatRequiredNotes
fromTsIntegerNUnix timestamp, seconds since epoch. Returns data with timestamp >= fromTs. Default, if not specified: now minus 1 hour.
toTsIntegerNUnix timestamp, seconds since epoch. Returns data with timestamp < toTs. Default, if not specified: 1 hour after fromTs.
filter[group]Enum (String)NNew in v3.1: When present, and set to phases (currently the only supported value), the energy data entries will be collapse to reflect the phases.grouping configuration of the device. More information in Phase grouping

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/long-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 nameFormatRequiredNotes
filter[group]Enum (String)NNew in v3.2: When present, and set to phases (currently the only supported value), the energy data entries will be collapse to reflect the phases.grouping configuration of the device. More information in Phase grouping

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
    ]
}

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 nameFormatRequiredNotes
filter[group]Enum (String)NNew in v3.2: When present, and set to phases (currently the only supported value), the energy data entries will be collapse to reflect the phases.grouping configuration of the device. More information in Phase grouping

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 nameFormatRequiredNotes
fromTsIntegerNUnix timestamp, seconds since epoch. Returns data with timestamp >= fromTs. Default, if not specified: first long energy entry.
toTsIntegerNUnix timestamp, seconds since epoch. Returns data with timestamp < toTs. Default, if not specified: 7 days after fromTs.
granularityStringNValid values: 5m, 15m, 30m, hour, day, week, month. Default, if not specified: 5m.
timezoneStringNRequired 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)NNew in v3.2: When present, and set to phases (currently the only supported value), the energy data entries will be collapse to reflect the phases.grouping configuration of the device. More information in Phase grouping

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

GranularityMax. time period
5m7 days
15m14 days
30m31 days
hour3 months
day3 years
week5 years
month10 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 nameFormatRequiredNotes
filter[group]Enum (String)NNew in v3.2: When present, and set to phases (currently the only supported value), the energy data entries will be collapse to reflect the phases.grouping configuration of the device. More information in Phase grouping

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 nameFormatRequiredNotes
filter[group]Enum (String)NNew in v3.2: When present, and set to phases (currently the only supported value), the energy data entries will be collapse to reflect the phases.grouping configuration of the device. More information in Phase grouping

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 nameFormatRequiredNotes
fromTsIntegerNUnix timestamp, seconds since epoch. Returns data with timestamp >= fromTs. Default
toTsIntegerNUnix 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

None.

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

None.

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 QuantityFieldsData TypeUnit of Measurement
Real EnergyeReal, eRealPositive, eRealNegativeIntegerJ (Joules)
Reactive EnergyeReactive, eReactivePositive, eReactiveNegativeIntegerJ (Joules)
VoltagevRMS, vRMSMin, vRMSMaxFloatV (Volts)
CurrentiRMS, iRMSMin, iRMSMaxFloatA (Amperes)
FrequencyfrequencyFloatHz (Hertz)
DurationdurationIntegerSeconds
TimestamptimestampIntegerUnit 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.