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 |
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 |
---|---|---|
|
no |
Pagination parameter. Defaults to 0. |
|
no |
Pagination parameter. Defaults to 1000. Min: 10, Max: 1000. |
-
skip
andlimit
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 |
---|---|---|
|
no |
Epoch timestamp. Defaults to different values depending on the granularity. |
|
no |
Epoch timestamp. Defaults to now. |
|
no |
Possible values: |
|
no |
Compulsory if a granularity among 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 |
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 |
---|---|---|
|
no |
Epoch timestamp. Defaults to start of today UTC. |
|
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 |
---|---|
|
V (Volts) |
|
A (Amperes) |
|
Hz (Hertz) |
|
J (Joules) |
|
J (Joules) |
|
s (seconds) |
|
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 |
---|---|---|
|
5 seconds |
|
|
24hrs |
|
Headers
Each API calls returns the following headers
tps / tpd header |
Meaning |
---|---|
|
The |
|
|
|
The |
|
|
|
The time (in seconds) to wait for a new interval to start |
|
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 |
|
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 |
|
The request or one of its parameters are malformed. See the |
404 |
|
The requested resource does not exist OR the provided |
500 |
|
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 |
|
returns items 0 to 99. |
2 |
|
returns items 100 to 199. |
3 |
|
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 |
---|---|---|
|
12 hrs |
8640 |
|
5 days |
1440 |
|
15 days |
1440 |
|
30 days |
1440 |
|
30 days |
720 |
|
180 days |
180 |
|
180 days |
26 |
|
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 |
|
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 |
2 |
|
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.