Differences between v2 and v3+
We have aimed to maintain backwards compatibility as much as possible between v3 and v2 API. However, there are some (mostly minor) impelementation variations, which are outlined here.
Base URL
The v3 API uses a different URL scheme.
Instead of /v2 as a path for the URL, the sub-domain contains the version information.
For example:
- v2:
https://api.wattwatchers.com.au/v2/<endpoint> - v3:
https://api-v3.wattwatchers.com.au/<endpoint>
Week definition is different
v2 calculates weeks from Sunday 00:00 in the local time (specified by timezone). v3+ implements ISO8601 with first day of the week = Monday.
204 responses when no data available
For devices that have no data stored in the system, the return for Long Energy, Short Energy and Modbus data is a 204 No content response.
This distinguishes this use case from when the device has data in the system, but where there is no data for the specified period (200 OK returned with an empty array as the value []).
fromTs default value
For long energy, if fromTs is not specified, it is interpreted by the API as "first recorded long energy data entry for this device."
For short energy, if fromTs is not specified, it is set to 1 hour prior to toTs. If no toTs is specified, this is interpreted as 1 hour prior to now.
toTs default value
For long energy, if toTs is not specified, it is reset to the maximum time period based on the fromTs and specified granularity.
For short energy, if toTs is not specified, it is set to now if fromTs is not specified or if fromTs is > 1 hour before now. If fromTs is specified and is < 1 hour before now, and no toTs is specified, toTs defaults to 1 hour after fromTs.
Interaction between fromTs and toTs
When the period between fromTs and toTs is larger than the maximum time period (see below), a 422 HTTP status is returned.
For long energy, if fromTs is set to zero and toTs is set to a non-zero value, a 422 HTTP status is returned.
Maximum time period
Each individual request is limited to allow a maximum time period for the data returned. You can issue multiple requests to retrieve longer time periods.
For long energy
The v2 API implements limits by restricting the number of entries returned in a single request. v3 implements checks on the time period specified instead and issues an HTTP status error if specified paramaters exceed these boundaries.
| Granularity | Max time period | v2 | Max number of entries | Notes |
|---|---|---|---|---|
| 5m | 1 week (7 days) | 5 days | 2,016 | Increased to 7 days in v3 to allow for "week at a time" queries. |
| 15m | 2 weeks (14 days) | 15 days | 1,344 | Reduced to 14 in Mercury to match week breakdown. |
| 30m | 1 month (31 days) | 30 days | 1,488 | Increased to 31 in Mercury to allow for "month at a time" queries. |
| hour | 3 months (93 days) | 30 days | 2,232 | Increased to allow for up to 3 months. |
| day | 3 years (1,096 days) | 180 days | 1,096 | Accommodates a single leap year occurring in time period. |
| week | 5 years (1,826 days) | 180 days | 260 | Accommodates a single leap year occurring in time period. |
| month | 10 years (3,652 days) | 180 days | 120 | Accommodates two leap years occurring in time period. |
For short energy
The maximum time period for a single request is 12 hours (same as v2 API).
Long energy data migration
By default, devices migrated to the v3 API will only have historical data from 1 Jan 2019 brought across. Please contact your Wattwatchers account representative if you require a longer historical record in the v3 system.
Short energy data retention
Short energy records are only retained for 31 days from receipt. Specifying a toTs that is earlier than 31 days ago will result in a 422 status response.
Pagination for devices endpoint
The /devices endpoint no longer supports pagination (all results are returned) and thus does not return any headers related to pagination.
Rate limits
To help ensure that problematic applications and potential security threats don't impact other users of the system, we continue to employ methods of rate limiting for the v3 API.
Default TPS limits have been increased to enable a greater number of requests per second per customer. The default for new accounts will auto-scale on the basis of the number of devices in your API key. Review the API return headers for your current settings.