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/
 
IMPORTANT: Development environment for prototyping and testing
https://dev-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 keep the HTTPS session open using the standard web cookies during the data transmission.
  • 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. You must let us know if you change your data push frequency so we can reconfigure our system.

 

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)
}

Please note that:

  • pC_1, pC_2 and pC_3 consumption values should be the cumulative Wh values (Wh consumed since the beginning). Our software will calculate the Wh consumed during the time interval by subtracting successive Wh readings.
  • Data packets must be timestamped by the data source with the local sampling time. 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.
  • The timestamp format should comply to 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)
  • Only a selection of data types may be sent, not all parameters are expected for each transaction.
  • 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.
  • The JSON packet should not be sent with line breaks, but as a one line packet (the JSON examples with line breaks shown here are for clarity purposes)

 

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
}

Please note that data packets must be timestamped by the data source with the local sampling time. This is the time that will be shown in the dashboard. Data packets must also be sent in chronological order. The chronological order is important for the elaboration in real-time. The timestamp format comply to the ISO8601 standard (e.g. “2016-02-10T21:45:31.070+11:00”)

 

Examples

{
"id": "my_stream_id", => Data Stream ID
"tsISO8601": "2016-02-10T21:45:31.070+11:00", => Timestamp in ISO8601 format
"aP_1":1819.1300048828, => Active Power phase 1 in (W)
"aP_2":2385.669921875, => Active Power phase 2 in (W)
"aP_3":2155.8200683594, => Active Power phase 3 in (W)
"rP_1":604.09899902344, => Reactive Power phase 1 in (VA reactive)
"rP_2":1186.5400390625, => Reactive Power phase 2 in (VA reactive)
"rP_3":768.37298583984, => Reactive Power phase 3 in (VA reactive)
"apP_1":1916.8199462891, => Apparent Power phase 1 in (VA)
"apP_2":2664.4499511719, => Apparent Power phase 2 in (VA)
"apP_3":2288.6599121094, => Apparent Power phase 3 in (VA)
"v_1":7.5769100189209, => Voltage phase 1 in (Volts)
"v_2":10.568400382996, => Voltage phase 2 in (Volts)
"v_3":8.969220161438, => Voltage phase 3 in (Volts)
"c_1":10000, => Current phase 1 in (Ampere)
"c_2":252.11599731445, => Current phase 2 in (Ampere)
"c_3":255.16799926758, => Current phase 3 in (Ampere)
"pC_1":8423692, => Energy consumed in phase 1 in (Wh)
"pC_2":10273479, => Energy consumed in phase 2 in (Wh)
"pC_3":9786087, => Energy consumed in phase 3 in (Wh)
"v_12":399.6, => Phase-To-Phase Voltage between phase 1 and 2 (Volts)
"v_13":398.2, => Phase-To-Phase Voltage between phase 1 and 3 (Volts)
"v_23":401.07 => Phase-To-Phase Voltage between phase 2 and 3 (Volts)
}

will be sent as

{“id”: “my_stream_id”,”tsISO8601″: “2016-02-10T21:45:31.070+11:00″,”aP_1″:1819.1300048828,”aP_2″:2385.669921875,”aP_3″:2155.8200683594,”rP_1″:604.09899902344,”rP_2″:1186.5400390625,”rP_3″:768.37298583984,”apP_1″:1916.8199462891,”apP_2″:2664.4499511719,”apP_3″:2288.6599121094,”v_1″:7.5769100189209,”v_2″:10.568400382996,”v_3″:8.969220161438,”c_1″:10000,”c_2″:252.11599731445,”c_3″:255.16799926758,”pC_1″:8423692,”pC_2″:10273479,”pC_3″:9786087,”v_12″:399.6,”v_13″:398.2,”v_23”:401.07}

 

{
"id": "my_stream_id", => Data Stream ID
"tsISO8601": "2016-02-10T21:45:31.070+11:00", => Timestamp in ISO8601 format
"value":5554.23 => Generic value
}

will be sent as

{“id”: “my_stream_id”,”tsISO8601″: “2016-02-10T21:45:31.070+11:00″,”value”:5554.23}

 

Troubleshooting

You must log in to your Wattics Dev Dashboard using the credentials received as part of your API Startup Package.

https://dev-dashboard.wattics.com/
 

After log in you will find the three data points in your menu tree under the Breakdown tab.

To check if data is being received on Wattics’ end, you must go to the Breakdown tab, click on your data point and check the control panel on the right hand side. If Jan 1970 is shown then it means that no data has been received yet (please wait for at least two time intervals). The panel will otherwise update to today’s date, and you will be able to select that day and check the first data points coming in.

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 a standard HTTP GET request creating the URL in the following way (you will need to remove ‘dev-‘ from the url when pushing data to our production environment):

https://dev-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

Where can I find the API documentation

How can I upload data via the Wattics REST API

This page contains the JSON format specifications as well as the rules that your software must follow when pushing data to Wattics (e.g. units, timestamp format, authentication etc). Please make sure to read everything carefully first to ensure we get it right the first time. Any clarification needed by your software team, please email us at support@wattics.com.

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.
What do I need to start developing my API client

You must first read our API documentation:

How can I upload data via the Wattics REST API

Then you need to request an API Startup Package at support@wattics.com providing information about yourproject. Our team will send you:

  • HTTPs credentials (username and password)
  • Unique Data Stream IDs to use for three test data points (electricity, gas and environmental data)
  • Dashboard demo account in our dev environment (to verify that data is coming in nicely when you push it)

 

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.
How to test if my software client is working

You must log in to your Wattics Dashboard using the credentials received as part of your API Startup Package. After log in you will find the three data points in your menu tree under the Breakdown tab.

To check if data is being received on Wattics’ end, you must go to the Breakdown tab, click on your data point and check the control panel on the right hand side. If Jan 1970 is shown then it means that no data has been received yet (please wait for at least two time intervals). The panel will otherwise update to today’s date, and you will be able to select that day and check the first data points coming in.

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 a standard HTTP GET request creating the URL in the following way (you will need to remove ‘dev-‘ from the url when pushing data to our production environment):

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

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.

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.
What is the API URL to use for testing my software client

https://dev-web-collector.wattics.com/measurements/v2/unifiedjson/

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.
How often should my software client post data to the API

​The data push frequency can be adapted to your application requirements, as this frequency will define the granularity of the readings shown in the dashboard (e.g. if you push every 5 minutes you will have a 5-minute minimum granularity in the graphs).

It is important that you let us know what your data push frequency is at the start or whenever you decide to change it. This indeed allows us to configure our platform to detect broken communication when no data is coming in and issue real-time notifications.

If your software client does not push at regular intervals, you must choose the highest time period acceptable after which data communication can be considered as broken. All packets received during that time interval will be aggregated by our API and shown aggregated in your graphs.

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.
Can I push Power Factor and Harmonics measurements

Not at the moment, but these may be supported in the next version of our API. Please register your interest with so we can update you when these are available.

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.
What is the correct timestamp format?

Our API expects the standard ISO8601 yyyy-mm-ddThh:mm:ss.sss+|-hh:mm where “yyyy-mm-ddThh:mm:ss.sss” represents the local time and “+|-hh:mm” is the OFFSET to apply in order to obtain the UTC timestamp​. You can find more information here: “https://www.w3.org/TR/NOTE-datetime”.

For example, 1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.
What should I do when per phase readings are not available

If your meter or data system does not record individual readings per phase, you must use the _1 entries and omit the _2 and _3 entries. For example, you must push your total kWh to the pC_1 parameter.

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.

Anthony Schoofs

Chief Technical Officer at Wattics
Anthony drives Wattics' innovation on energy efficiency for industrial and grid environments. Anthony is also behind WSNbuzz.com, a blog covering technology advances within the smart grid and IoT markets, and was listed in 2011 amongst the top 100 IoT thinkers. Anthony was recently awarded the Globe Sustainability Research Award for his contribution to advancing knowledge on sustainability.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>