Wattics Energy Management Software API // Wattics Energy Management
Book a Demo

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.

Uploading your data to the Wattics Cloud Platform happens via our secure HTTPs Restful API, as depicted below in red.

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

 

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.

    https://dash.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 Data>Attributes tab. 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):

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

    https://dashboard.wattics.com/

    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 install

    At 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/folder

    Usage

    swarm config_file.ini

    CSV 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 install

    Getting 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_last

    Groups of measurements

    You may also want send groups of measurements.

    measurements = [simple_measurement1, electricity_measurement1, simple_measurement2, ...]
    
    agent.send(measurements, config)
    
    agent.wait_until_last
    simple_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_last

    Handlers 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
      }
    end

    Errors

    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)

    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 & Air Analytics Dashboard

    Learn more about the analytics tools in the Wattics platform to analyse energy and air quality performance in your facilities

    Check features

    Subscribe to our blog

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

    Subscribe