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.

 

Once received, data streams are processed in real-time through our back-end analytics engines to produce additional insights such as demand forecast, anomaly and wastage detection. As such, both original measurements and generated insights are immediately available to end-users on our web-based dashboard. The following contains important information to get started.

 

STEP 1: Request your API Startup Package

Your metered points (e.g. electrical meters) must be registered with Wattics before measurements are pushed via our RESTful API. HTTPs credentials must also be agreed to allow secure communication between the data collection system and Wattics.

As a way to start off with the integration phase, you must email our tech support team at support@wattics.com and request your API startup package. 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.

 

Request your API startup package 

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.

 

API Service URL

The Wattics Production RESTful API has one point of entry, which is used when the data push functionality has been fully tested:
https://web-collector.wattics.com/measurements/v2/unifiedjson/

Please note the use of https:// in the URL 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 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 success@wattics.com

JSON Packet Format

Electrical demand measurements (Active/Apparent/Reactive Power, Current, Phase Voltage, Line Voltage, THD) 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 phase 1 (Wh)
"pC_2":xxx, => Energy consumed phase 2 (Wh)
"pC_3":xxx, => Energy consumed phase 3 (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.

https://web-collector.wattics.com/measurements/v2/unifiedjson/?stream=MeterID

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. 

 

Hint: If no packet has been received the control panel on the right-hand side will show only year 1970 (see below).

You can also check the last data packet received in the meter status available in the Attributes tab, that you can access by hovering over your name in the top right corner. 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. You just need to issues a standard HTTP GET request creating the URL in the following way.

https://web-collector.wattics.com/measurements/v2/unifiedjson/?stream=DATASTREAMID

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.

https://dashboard.wattics.com/  

 

Please email Wattics at support@wattics.com for any questions regarding the technical integration and Web API.

API Troubleshooting

If you have a question that is not asked and answered on these pages, please contact us at support@wattics.com