RESTful API Documentation

The live energy APIs allow real time access to the energy data from Auditor devices.

API endpoint

The Wattwatchers APIs are available at https://api.wattwatchers.com.au/.

API Access

To gain access to the APIs it is necessary to obtain an apiKey from Wattwatchers.

  • Each apiKey:

    • is linked to a user account on our system

    • has a limit of concurrent API requests allowed (tps or transactions per second)

    • has a limit of daily API requests allowed (tpd or transactions per day)

You can request an apiKey from Wattwatchers as part of the onboarding process.
Each apiKey must be kept secure exactly like a password or access key.
See Throttling for more details on API throttling

Authentication

Each call is authenticated by setting the Authorization: Bearer header as described in the OAuth 2.0 specifications:

Authorization: Bearer <apiKey>

This header must be passed with all HTTPS requests as in the following curl example:

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

The choice of HTTPS ensures that the apiKey is never sent unprotected as both the requests and responses are encrypted.

Authorization

Currently each apiKey gives unrestricted read-only access to all the data (devices and energy) within the account it’s issued for.

Long Energy vs Short Energy

Long Energy

Long energy is sent by the devices to the server upon request. Long energy entries are stored on the devices on persistent storage (5min - or 300sec - granularity only).

Short Energy

Short energy instead is sent by the devices automatically every 5 to 295 seconds (depending on configuration) via UDP packets with no guarantee of delivery. Short energy entries are not currently stored on the devices and thus can be lost if the device looses connectivity with the server or simply if any UDP packet is lost during transmission (UDP has no guarantee of delivery)

API Calls

GET /v2/devices

Returns a list of all devices from your account. This call returns at most 1000 items and is paginated.

Params

Param Name Compulsory Notes

skip

no

Pagination parameter. Defaults to 0.

limit

no

Pagination parameter. Defaults to 1000. Min: 10, Max: 1000.

  • skip and limit are lenient parameters:

    • Invalid values will be silently discarded

    • Out of bound values will be converted to the closest in bound values

Example requests

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

curl -X GET -H "Authorization..." "https://api.wattwatchers.com.au/v2/devices?skip=1000"

Example reply

[
  "D800000000000",
  "D800000000001",
  "D800000000002",
  "D800000000003",
  "D800000000004",
  "D800000000005",
  "D800000000006",
  "D800000000007",
  "D800000000008",
  "D800000000009"
]

GET /v2/long-energy/:serial

Retrieves long energy data for a specific device.

A maximum of 6 months worth of long energy data can be returned by a single call depending on the granularity requested. See Limits and Pagination for more details on the limitations and how to retrieve large data sets.

This call is not paginated so the skip and limit parameters don’t apply and are ignored. Pagination is implicity obtained by setting the appropriate values for fromTs and toTs

Params

Param Name Compulsory Notes

fromTs

no

Epoch timestamp.

Defaults to different values depending on the granularity.

toTs

no

Epoch timestamp.

Defaults to now.

granularity

no

Possible values: 5m, 15m, 30m, hour, day, week, month.

timezone

no

Compulsory if a granularity among hour, day, week, month is specified.

Timezone values are used to determine the start of the hour, day, week or month, which are necessary to run the aggregations

Valid timezone values can be found here

This field defaults to Australia/Sydney.

Example requests

curl -X GET -H "Authorization..." "https://api.wattwatchers.com.au/v2/long-energy/D800000000000?fromTs=1451779200"

curl -X GET -H "Authorization..." "https://api.wattwatchers.com.au/v2/long-energy/D800000000000?fromTs=1451779200&granularity=day&timezone=Europe/London"

Example reply

[
    {
        "eReal": [
            -4,
            -11,
            1
        ],
        "eRealNegative": [
            4,
            11,
            0
        ],
        "eRealPositive": [
            0,
            0,
            1
        ],
        "eReactive": [
            -5,
            -5,
            -8
        ],
        "eReactiveNegative": [
            5,
            5,
            8
        ],
        "eReactivePositive": [
            0,
            0,
            0
        ],
        "vRMSMin": [
            249,
            249,
            249
        ],
        "vRMSMax": [
            250.2,
            250.2,
            250.2
        ],
        "iRMSMin": [
            0.022,
            0.022,
            0.022
        ],
        "iRMSMax": [
            0.023,
            0.023,
            0.023
        ],
        "timestamp": 1471389300,
        "duration": 300
    }
]

GET /v2/short-energy/:serial

Retrieves short energy data for a specific device.

A maximum of 12 hours worth of short energy data can be retrieved in one call. See Limits and Pagination for more details on how to retrieve large data sets.

This call is not paginated so the skip and limit parameters don’t apply and are ignored. Pagination is implicity obtained by setting the appropriate values for fromTs and toTs

Params

Param Name Compulsory Notes

fromTs

no

Epoch timestamp.

Defaults to start of today UTC.

toTs

no

Epoch timestamp.

Defaults to now.

Example request

curl -X GET -H "Authorization..." "https://api.wattwatchers.com.au/v2/short-energy/D800000000000"

Example reply

[
    {
        "eReal": [
            6,
            4,
            7,
            514,
            -520,
            0
        ],
        "eReactive": [
            -4,
            -4,
            -6,
            -1306,
            1322,
            0
        ],
        "vRMS": [
            246.9,
            248.1,
            247.9,
            247,
            248.2,
            247.9
        ],
        "iRMS": [
            0.024,
            0.024,
            0.025,
            1.262,
            1.27,
            0.024
        ],
        "timestamp": 1472986800,
        "duration": 5,
        "frequency": 50.09
    }
]

Notes

Energy Units

The following units of measurement are used across all energy calls

Physical Quantity Unit of Measurement

Voltage

V (Volts)

Current

A (Amperes)

Frequency

Hz (Hertz)

Real Energy

J (Joules)

Reactive Energy

J (Joules)

Duration

s (seconds)

Timestamp

s (seconds) since Epoch time

Throttling

Each API key is provided with tps (transactions per seconds) and tpd (transactions per day) limits

tps and tpd are enforced via a token bucket credit system.

Each API call consumes a credit and credit are replenished after a fixed interval according to the following table

Limit type Interval Start of period examples

tps

5 seconds

1481340180 (10/12/2016, 14:23:00 UTC)
1481340185 (10/12/2016, 14:23:05 UTC)
1481340190 (10/12/2016, 14:23:10 UTC)
…​

tpd

24hrs

1481328000 (10/12/2016, 00:00:00 UTC)
1481414400 (11/12/2016, 00:00:00 UTC)
1481500800 (12/12/2016, 00:00:00 UTC)
…​

Headers

Each API calls returns the following headers

tps / tpd header Meaning

X-RateLimit-TpsLimit

The tps/tpd limit linked to the supplied API key

X-RateLimit-TpdLimit

X-RateLimit-TpsRemaining

The tps/tpd remaining value for the current interval

X-RateLimit-TpdRemaining

X-RateLimit-TpsReset

The time (in seconds) to wait for a new interval to start

X-RateLimit-TpdReset

Error Codes

All API calls return HTTP response code 200 on success

In case of error a JSON payload like the following is returned:

{
    "httpCode": 404,
    "error": "NOT_FOUND",
    "message": "No device with serial D704206049101"
}

The possible error codes are as follows

Http Response Code Error Code Possible reasons

403

UNAUTHORIZED

The provided credentials are not valid or have been disabled

Alternatively you’ve exceeded the provisioned TPS (transactions per seconds) or TPD (transactions per day) limits. TPS limits resets immediately whereas TPD limits every 24hrs at midnight UTC

400

BAD_REQUEST

The request or one of its parameters are malformed.

See the message field for more information

404

NOT_FOUND

The requested resource does not exist OR the provided apiKey does not grant access to it

500

INTERNAL_SERVER_ERROR

There has been a server problem processing your request.

Our operations team is alerted in case of any server side errors

Limits and Pagination

When querying for large data sets multiple API calls may be required.

Within our APIs pagination works differently depending on the context as different API calls work with with different defaults.

Skip / Limit parameters

When a call accepts skip and limit parameters they can be used to paginate through result sets as in the following example:

Let’s suppose we have a total of 250 devices in our account. If we need to get all the devices in our account we would proceed with multiple calls as follows:

Call URL Notes

1

GET /v2/devices?limit=100

returns items 0 to 99.

2

GET /v2/devices?skip=100&limit=100

returns items 100 to 199.

3

GET /v2/devices?skip=200&limit=100

returns items 200 to 249.

As our resultset with call #3 is smaller than limit the script can now terminate as there are no more devices to query for.

Energy calls

The get long and short energy API calls have built in limits to ensure stability of our backend and are paginated implicitly:

Granularity Limit Max entries returned

5s

12 hrs

8640

5m

5 days

1440

15m

15 days

1440

30m

30 days

1440

hour

30 days

720

day

180 days

180

week

180 days

26

month

180 days

6

Let’s suppose we are querying for long energy data as follows:

  • serial: D704206049100

  • fromTs: Fri, 01 Jan 2016 00:00:00 GMT (1451606400) inclusive

  • toTs: Thu, 07 Jan 2016 00:00:00 GMT (1452124800) exclusive

  • granularity: 5min

There are 518400 seconds and 1728 5min entries between Fri, 01 Jan 2016 00:00:00 GMT and Thu, 07 Jan 2016 00:00:00 GMT.

As the maximum number of entries returned with a Long energy query with this '5min' granularity is 1440 at least 2 API calls are necessary.

In order to determine the value of the fromTs parameter in call #2 it’s necessary to inspect the payload returned by call #1 as follows:

Call URL Notes

1

GET /v2/long-energy/D704206049100?fromTs=1451606400

Returns 1440 entries in ascending order with timestamp values between 1451606400 (first element) and 1452038100 (last element).

We then use 1452038100 + 300 = 1452038400 as the fromTs for the following call.

2

GET /v2/long-energy/D704206049100?fromTs=1452038400

Returns 288 entries with timestamp values between 1452038400 (first element) and 1452124500 (last element).

As our resultset with call #3 is smaller than our expected limit the script can now terminate as there are no more entries to query for.