API
The Wattics energy management platform is designed to integrate measurements from meters, BMS, head end systems, databases and other data providers. Our REST API allows those data systems to interact with our backend programmatically, over simple HTTP requests. This means that you can automate data push to the Wattics platform from your own application.
Request your API Startup Package
Your data 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.
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.
API Service URL
The Wattics RESTful API has one point of entry, which is used for prototyping and testing, and 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.
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.
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. When moving to Production you will be able to create data points with the ferquency of your choice.
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.
JSON 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)
}
should 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
}
should be sent as
{“id”: “my_stream_id”,”tsISO8601″: “2016-02-10T21:45:31.070+11:00″,”value”:5554.23}Testing
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.
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):
[Refer to API documentation: https://developers.wattics.com/]
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.
Once tests are green the Wattics Team will enable new organisations, sites and data points 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.
Support
If you can’t find an answer in the resources above, you can contact us for any questions regarding any problems, questions, or comments you have about the Wattics platform.
REST API Java Library
Download & build
You’ll need a local copy of the example code to work through this quickstart. Download the code from our Github repository:
$ git clone https://github.com/Wattics/api-client-java
$ cd api-client-java
$ gradle installAt this point you will have the library available as a maven dependency, so you can embed this snippet in your pom.xml:
com.wattics
api-client
0.2.0
Example code
Here’s some basic code to get started with the library:
import com.wattics.*;
import static com.wattics.Config.Environment.DEVELOPMENT;
import static java.time.LocalDateTime.now;
public class Main {
public static void main(String[] args) {
Agent agent = Agent.getInstance();
agent.addMeasurementSentHandler((measurement, httpResponse) -> {
System.out.println(measurement);
System.out.println(httpResponse);
});
// Config config = new Config(PRODUCTION, "username", "password");
Config config = new Config(DEVELOPMENT, "username", "password");
SimpleMeasurement simpleMeasurement = new SimpleMeasurement();
simpleMeasurement.setId("meter-id-01");
simpleMeasurement.setTimestamp(now());
simpleMeasurement.setValue(12.5);
agent.send(simpleMeasurement, config);
ElectricityMeasurement electricityMeasurement = new ElectricityMeasurement();
electricityMeasurement.setId("meter-id-02");
electricityMeasurement.setTimestamp(now());
electricityMeasurement.setActivePowerPhaseA(5.12);
electricityMeasurement.setActiveEnergyPhaseA(1.5);
// ...
agent.send(electricityMeasurement, config);
}
}REST API Python app
Installation
pip install /path/to/swarm/folderUsage
swarm config_file.iniCSV format
The CSV structure consists of:
timestamp first measurements … last measurement
If the CSV includes all electrical parameters, then the measurements are listed in the Wattics API docs, otherwise only one measurement column is allowed.
- No header is expected
- Measurements values are float numbers, where the decimal digits separator is “.” (dot)
- The expected separator character is “,” (comma)
- The expected timestamp format is “%Y-%m-%d %H:%M:%S” (see python docs for more details)
REST API Ruby GEM
Installation
Add the gem to you Gemfile and run bundle install.
gem 'wattics-api-client'
bundle installGetting started
Here is an example code to get you started with the API. Remember to use a valid username and password. Important: wait_until_last must be included at the end of all sends, missing this command may cause the loss of data.
require 'wattics-api-client'
agent = Agent.get_instance
agent.add_measurement_sent_handler do
-> (measurement, response) {
puts "#{response.code} - #{measurement}"
}
end
# config = Config.new(:PRODUCTION, "username", "password")
config = Config.new(:DEVELOPMENT,'username', 'password')
simple_measurement = SimpleMeasurement.new
simple_measurement.id = 'gas-meter-id-01'
simple_measurement.value = 12.3
simple_measurement.timestamp = Time.now
agent.send(simple_measurement, config)
electricity_measurement = ElectricityMeasurement.new
electricity_measurement.id = "elec-meter-id-02"
electricity_measurement.timestamp = Time.now
electricity_measurement.active_energy_phase_a = 5.12
electricity_measurement.active_energy_phase_b = 1.5
# ...
agent.send(electricity_measurement, config)
agent.wait_until_lastGroups of measurements
You may also want send groups of measurements.
measurements = [simple_measurement1, electricity_measurement1, simple_measurement2, ...]
agent.send(measurements, config)
agent.wait_until_lastsimple_measurements = [simple_measurement1, simple_measurement2, simple_measurement3, ...]
eletric_measurements = [electric_measurement1, electric_measurement2, electric_measurement3, ..]
agent.send(simple_measurements, config)
agent.send(electric_measurements, config)
agent.wait_until_lastHandlers for callbacks
After sending the data you may want to check if it was sent correctly. For this you have access to measurement and response. You can set different handlers for the callbacks using add_measurement_sent_handler. You can set as many handlers as you like.
Priting to the console and saving to a file.
agent.add_measurement_sent_handler do
-> (measurement, response) {
puts "#{response.code} - #{measurement}"
}
end
agent.add_measurement_sent_handler do
-> (measurement, response) {
File.open('results.txt', 'a') do |line|
line.puts "#{response.code} - #{measurement}"
end
}
endErrors
In case there is an error sending a point data, the gem will keep trying until it is sent. Errors will be logged to the terminal. See some common errors.
Not registered or wrong credentials.
$ Server Response: HTTP Status 401 - Full authentication is required to access this resource
Internet connection down.
$ Server Response: Failed to open TCP connection to web-collector.wattics.com:443 (getaddrinfo: nodename nor servname provided, or not known)
Parallel Sends
When running agent.get_instance, it will spin twice as many as virtual processors as system has available. Ex. If your system is a dual core, and has 4 virtual processors, the gem will spin up 8 parallel send processes for maximum performance.
In some cases you may want to limit how many processes are created. You can specify this when creating an instance of the agent. agent.get_instance(number of processors) In case you exceed the maximum limit, it will set for to the default maximum.
# Limiting send processes to two.
agent.get_instance(2)Contact us to get a quote or a custom-tailored demonstration with one of our business advisors.
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