DATA INTEGRATION
REST API – Smart Meter Energy Data API
How can I upload data via the Wattics REST API?
The Wattics platform is designed to integrate measurements from meters, BMS, head end systems, databases and other data providers.
Overview
3rd party data collection systems can interface the Wattics Cloud Platform via our secure HTTPs Restful API, as depicted below in red. This process connects your data and system to our cloud-based energy analytics dashboard, enabling new product offering for your customers.
Your metered points (e.g. electrical meters) must be registered with Wattics before measurements are pushed to our RESTful API. HTTPs credentials must also be agreed to allow secure communication between your data collection system and Wattics.
Step 1: Request your API Startup Package
As a way to start off with the integration phase, you must request your API startup package using the form below. Our team will send you within 24 hours:
- HTTPs credentials (username and password)
- Unique Data Stream IDs to use for three test data points (electricity, gas and environmental data).
- Dashboard demo account (to verify that data is coming in nicely when you push it)
Credentials for HTTP authentication can be agreed per meter, per end-user, per site or per partner when moving to production. Same for Data Stream IDs and dashboard accounts.
Step 2: Pushing data to Wattics
The Wattics RESTful API accepts electricity, gas, water and other data types at the same URL, but two distinctive JSON formats must be used depending on the data pushed.
APL Service URL
The Wattics Production RESTful API has one point of entry, which is used when the data push functionality has been fully tested:
[Refer to API documentation: https://developers.wattics.com/]
Please note the use of https:// in the URLs above. All Wattics API communication is encrypted over HTTPs. Non-secure requests are automatically rejected, so we recommend establishing a test connection with the secure API entry point before sending sensitive data.
IMPORTANT: Clarifications on API client implementation
- Your data push implementation must use the POST method
- Your data push implementation must use basic authentication
- Your data push implementation must send one packet per HTTP transaction.
- Our data collection system expects to receive data at the agreed time interval, so data holes will be assumed if no packets are being received when due. Note that if the datapoint has been registered to receive data every 5 minutes and you are pushing less frequent (e.g. every 15 min) you will not see data on your platform. To resolve, you must log in with admin credentials, go to the Admin section, identify the datapoint and change transmission frequency configuration accordingly. Otherwise, contact us at [email protected]
JSON Packet Format
Electrical demand measurements (Active/Apparent/Reactive Power, Current, Phase Voltage, Line Voltage) and electrical energy readings must be encapsulated in the following JSON format with associated units:
{
"id":"xxx", => Unique Meter ID
"tsISO8601":"xxx", => Local Timestamp in ISO8601 format (yyyy-mm-ddThh:mm:ss.sss+|-hh:mm)
"aP_1":xxx, => Active Power phase 1 in (W)
"aP_2":xxx, => Active Power phase 2 in (W)
"aP_3":xxx, => Active Power phase 3 in (W)
"rP_1":xxx, => Reactive Power phase 1 in (VA reactive)
"rP_2":xxx, => Reactive Power phase 2 in (VA reactive)
"rP_3":xxx, => Reactive Power phase 3 in (VA reactive)
"apP_1":xxx, => Apparent Power phase 1 in (VA)
"apP_2":xxx, => Apparent Power phase 2 in (VA)
"apP_3":xxx, => Apparent Power phase 3 in (VA)
"v_1":xxx, => Voltage phase 1 in (Volts)
"v_2":xxx, => Voltage phase 2 in (Volts)
"v_3":xxx, => Voltage phase 3 in (Volts)
"c_1":xxx, => Current phase 1 in (Ampere)
"c_2":xxx, => Current phase 2 in (Ampere)
"c_3":xxx, => Current phase 3 in (Ampere)
"pC_1":xxx, => Energy consumed since beginning in phase 1 in (Wh)
"pC_2":xxx, => Energy consumed since beginning in phase 2 in (Wh)
"pC_3":xxx, => Energy consumed since beginning in phase 3 in (Wh)
"v_12":xxx, => Phase-To-Phase Voltage between phase 1 and 2 in (Volts)
"v_13":xxx, => Phase-To-Phase Voltage between phase 1 and 3 in (Volts)
"v_23":xxx => Phase-To-Phase Voltage between phase 2 and 3 in (Volts)
}EXAMPLE electrical JSON packet:
{“id”:”yourMeterID”,”tsISO8601″:”2017-12-01T12:00:00.000+00:00″, “aP_1″:123,”aP_2″:123,”aP_3”:123, “rP_1”:123, “rP_2”:123, “rP_3”:123, “apP_1″:123,”apP_2″:123,”apP_3”:123, “v_1″:123,”v_2”:123, “v_3”:123, “c_1”:123, “c_2″:123,”c_3”:123, “pC_1”:123, “pC_2″:123,”pC_3”:123, “v_12”:123, “v_13″:123,”v_23”:123
}Single-value data points (gas, water, heat, temperature, production, any numeric value) must be encapsulated in the following JSON format:
{
"id":"xxx", => Unique Meter ID
"tsISO8601":"xxx", => Local Timestamp in ISO8601 format (yyyy-mm-ddThh:mm:ss.sss+|-hh:mm)
"value":xxx, => Value
}EXAMPLE numeric value JSON packet:
{“id”:”yourMeterID”,”tsISO8601″:”2017-12-01T12:00:00.000+00:00″, “value”:123}IMPORTANT NOTES:
- The JSON packet must be sent in one line, no line breaks.
- Data packets must be timestamped with local time (where the meter is located). This is the time that will be shown in the dashboard.
- Data packets must be sent in chronological order. The chronological order is important for the elaboration in real-time. Note that the system will discard all packets not sent chronologically
- The timestamp format must comply with the ISO8601 standard (e.g. “2016-02-10T21:45:31.070+11:00” with 2016-02-10T21:45:31.070 the local time and 11:00 the timezone offset)
- You can send a subset of the parameters in your JSON packet, for example only energy in watt-hours
- If you only have one total value for a data point you must use the first parameter to transmit that value, e.g. total kWh should be sent to pC_1.
Data Acknowledgement
The Wattics API uses the following error codes for developers to check if the data is received correctly:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request — Your request is invalid. |
| 401 | Unauthorized — Your API key is wrong. |
| 403 | Forbidden — The resource requested is not allowed to the user who owns the token. |
| 404 | Not Found — The specified resource could not be found. |
| 500 | Internal Server Error — We had a problem with our server. Try again later. |
| 503 | Service Unavailable — We’re temporarily offline for maintenance. Please try again later. |
You must implement an error treatment for each of the above status code and retry transmission until you get status=200. For example:
if (response != null && response.getStatusLine().getStatusCode() >= 400) {
throw new IOException(response.getStatusLine().getReasonPhrase());
}The Java API library with the above code can be found here.
You can also check the latest processed packet that you sent through a GET request. You need to issues a standard HTTP GET request creating the URL in the following way.
[Refer to API documentation: https://developers.wattics.com/]
Troubleshooting
Visually through the user interface
You must log in to your Wattics Dashboard using your credentials.
Go to your breakdown tab, click on the datapoint associated with your meterID. Check if the data is displayed on the graph. Note that in order to display the first point, you must have sent at least two packets.
You can also check the last data packet received in the meter status available in the Attributes tab, that you can access by navigating to the data tab and then clicking on the attributes icon in the dashboard. If the meter status displays “Invalid Date” means that no data has been received yet.
In case you want to validate your JSON format, you can use third-party REST plugins for Firefox and Chrome which are great to push data and check if any error is returned. Sometimes you can spot a missing parenthesis or an error code indicating an incorrect password. You can also use GET calls on our API to check the last data packet received and stored on Wattics’ end to confirm that packets have been received.
Finally, when debugging, please remember to also check the timestamps and values shown in our dashboard, as these could reveal incorrect time and unit settings on your end. Once all is verified we can experiment pushing a batch of historical data and confirm that testing is done before moving to the production environment.
STEP 3: Getting Started with Wattics
Once tests are green the Wattics Team will enable you on our Production API and Production Dashboard, so you can start pushing data for real sites and customers.
User accounts will be created to allow end-users to log in to their user-friendly dashboard online to analyse and manage energy use once data push is operational.
Please email Wattics at [email protected] for any questions regarding the technical integration and Web API.
Create your own integration
Not supported yet? Don’t be left behind and integrate now
Go to the pageSubscribe to our blog
Sign up to keep up-to-date with what’s happening within the industry
Subscribe