DATA INTEGRATION

REST 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.

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.

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:
https://web-collector.wattics.com/measurements/v2/unifiedjson/

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 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 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.

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. 

Wattics energy monitoring
Hint: If no packet has been received the graph will show only year 1970 with no data (see below).

Wattics energy analytics
 

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.

Wattics energy analytics dashboard

Wattics metering
Wattics “Invalid Date” display

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.

https://dashboard.wattics.com/
wattics energy management software

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


0 people found this article useful

Contact us to get a quote or a custom-tailored demonstration with one of our business advisors.

+353 1415 1242
info@wattics.com
Contact us

Create your own integration

Not supported yet? Don’t be left behind and integrate now

Go to the page

Energy Learning community online

Be part of the big picture, share your knowledge and get access to experience and expertise from others

Visit our forum

Subscribe to our blog

Sign up to keep up-to-date with what’s happening within the industry

Subscribe