Requirements

To use our API, please check our license model.

API description

Under smart-me API all available API commands and their description can be seen.

Individual API commands used OBIS codes as return values. Details about the OBIS codes are below.

Obis Codes

Individual API commands used OBIS Codes as return values. 

OBIS Codes are used to describe a (meter) value. 

Obis Codes (Excel)

Tip for decoding: On this Website (German) you can read about the coding system. If you click on a medium there, you will see what the digits of the code stand for in each case.

Authentication

Basic Auth

smart-me API uses "Basic Authentication". Every call to the API must include the Authentication. HTTP Basic Authentication allows credentials (such as a username and password or an API token) to be transferred in HTTP headers. The secret is encoded using Base64.

OAuth 2.0

smart-me supports the authorization framework OAuth 2.0. External applications can apply for access to an account without having to know the login credentials.

Migration for partners who used OAuth before 22.05.2023

If you no longer require OAuth authentication, you do not need to do anything.

Before 22.05.2023, smart-me created the OAuth client ID for our partners. 

From 22.05.2023 onwards, the partner must create the OAuth client ID himself.

Which steps are necessary for a successful migration on 22.05.2023?

Why are we migrating?:

Restrictions:

After the Big Bang changeover from 22.05.2023:

Before 22.05.2023:

On / From 22.05.2023

OAuth information

smart-me supports the authorisation framework OAuth 2.0. External applications can request access to an account without knowing the credentials.

Setting up OAuth in the smart-me portal

The prerequisite for using oAuth is an account with the professional licence model. If you do not yet have an account with the professional licence model, you must purchase 1 licence.

Add oAuth applications

Required information

Grants & Endpoints

The implementation of OAuth is not described on our wiki. For example, you can find the necessary information to implement oAuth on this page: https://oauth.net/2/ 

Supported Grants (Flows) for oAuth Confidential and Public Applications:

- Authorization Code

- Authorization Code with PKCE

- Implicit Flow (deprecated)

- Device Code

- Refresh Token

Supported Grants (Flows) for oAuth Device (Client Credentials) Applications:

- Client Credentials

smart-me Endpoints

- Authorization: /api/oauth/authorize/

- Token: /api/oauth/token/

- Device Code: /api/oauth/device

Realtime (Webhook) API

The smart-me Realtime (Webhooks) API allows you to subscribe to new data of a device. You can subscribe to a single device or to all devices of a user. When a device sends new data to the cloud, a webhook sends this data as a POST request to a reconfigured URL. More Information [1]

Proto File

package RealtimeApi.Containers;

import "bcl.proto"; // schema for protobuf-net's handling of core .NET types


message DeviceData {

   required bcl.Guid DeviceId = 1;

   required bcl.DateTime DateTime = 2;

   repeated DeviceValue DeviceValues = 3;

}

message DeviceDataArray {

   repeated DeviceData DeviceDataItems = 1;

}

message DeviceValue {

   required bytes Obis = 1;

   required double Value = 2;

}

Proto File without BCL

syntax = "proto2";

package com.company;


message TimeSpan {

  required sint64 value = 1; // the size of the timespan (in units of the selected scale)

  optional TimeSpanScale scale = 2; // the scale of the timespan [default = DAYS]

  enum TimeSpanScale {

    DAYS = 0;

    HOURS = 1;

    MINUTES = 2;

    SECONDS = 3;

    MILLISECONDS = 4;

  TICKS = 5;


    MINMAX = 15; // dubious

  }

}


message DateTime {

  optional sint64 value = 1; // the offset (in units of the selected scale) from 1970/01/01

  optional TimeSpanScale scale = 2; // the scale of the timespan [default = DAYS]

  optional DateTimeKind kind = 3; // the kind of date/time being represented [default = UNSPECIFIED]

  enum TimeSpanScale {

    DAYS = 0;

    HOURS = 1;

    MINUTES = 2;

    SECONDS = 3;

    MILLISECONDS = 4;

 TICKS = 5;


    MINMAX = 15; // dubious

  }

  enum DateTimeKind

  {     

     // The time represented is not specified as either local time or Coordinated Universal Time (UTC).

     UNSPECIFIED = 0;

     // The time represented is UTC.

     UTC = 1;

     // The time represented is local time.

     LOCAL = 2;

   }

}


message Guid {

  required fixed64 lo = 1; // the first 8 bytes of the guid (note:crazy-endian)

  required fixed64 hi = 2; // the second 8 bytes of the guid (note:crazy-endian)

}


message DeviceData {

   required Guid DeviceId = 1;

   required DateTime DateTime = 2;

   repeated DeviceValue DeviceValues = 3;

}

message DeviceDataArray {

   repeated DeviceData DeviceDataItems = 1;

}

message DeviceValue {

   required bytes Obis = 1;

   required double Value = 2;

}

Examples

API examples

REST API Samples

HTML / Javascript (jquery) Examples

Get all devices

<html>

<head>

    <title>smart-me REST API Sample</title>

    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>

</head>

<body>

    <h1>Get all devices</h1>

    <ul id="DeviceList">

    </ul>


    <script type="text/javascript">

        var smartmeUserName = "YOUR_USERNAME";

        var smartmePassword = "YOUR_PASSWORD";


        function GetAllDevices() {

            var targetUrl = "https://api.smart-me.com/api/Devices/";


            $.ajax({

                url: targetUrl,

                type: "get",

                cache: false,

                headers: {

                    "Authorization": "Basic " + btoa(smartmeUserName + ":" + smartmePassword)

                },

                dataType: "json",

                error: function(jqXHR, exception) {

                    alert(exception);

                },

                success: function(json) {


                    json.forEach(function(element) {

                        // Do something

                        $("#DeviceList").append($("<li>").text(element.Name + ": " + element.CounterReadingImport + " " + element.CounterReadingUnit));

                    });

                }

            });

        }


        // On document load

        $(document).ready(function() {


            // Get all smart-me devices

            GetAllDevices();


        });

    </script>


</body>

</html>

Create and update device

<html>


<head>

    <title>smart-me REST API Sample</title>

    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>

</head>


<body>

    <h1>Create and update devices</h1>


    <button type="button" id="CreateNewDeviceButton">Create new device</button>


    <script type="text/javascript">

        var smartmeUserName = "YOUR_USERNAME";

        var smartmePassword = "YOUR_PASSWORD";


        var counterValueImport = 0.0;

        var counterValueExport = 0.0;

        var activePowerTempValue = 0.1;


        // The ID of the device

        var deviceID = null;


        function GetElectricityDevice(id, power, energyImport, energyExport) {

            var deviceObject = new Object();


            if (id != null) {

                // Object with an ID updates the existing device. Object without an ID creates a new one

                deviceObject.ID = id;

            }


            // Add all data

            deviceObject.Name = "My test device";

            deviceObject.Serial = 12345678;

            deviceObject.DeviceEnergyType = "MeterTypeElectricity"; // MeterTypeWater for Water, MeterTypeGas for Gas, MeterTypeHeat for Heat


            // Set active power in kW

            deviceObject.ActivePower = power;


            // Set countervalues import (in kWh)

            deviceObject.CounterReading = energyImport;


            // Set countervalues export (in kWh) 

            deviceObject.CounterReadingExport = energyExport;


            return deviceObject;

        }


        function CreateUpdateDevice(deviceObject) {


            var targetUrl = "https://api.smart-me.com/api/Devices/";


            var postData = JSON.stringify(deviceObject);


            $.ajax({

                    url: targetUrl,

                    type: "post",

                    cache: false,

                    headers: {

                        "Authorization": "Basic " + btoa(smartmeUserName + ":" + smartmePassword)

                    },

                    dataType: "json",

        contentType: "application/json; charset=utf-8",

              data: postData,

                    error: function(jqXHR, exception) {

                        alert(exception);

                    },

                    success: function(json) {


                        // The device was created or updated

                        deviceID = json.Id;

                        $('#CreateNewDeviceButton').text("Update device");


                        alert("OK! device ID: " + json.Id);

            }

                    });

            }


            // On document load

            $(document).ready(function() {


                $('#CreateNewDeviceButton').click(function(e) {

                    // No Postback

                    e.preventDefault();


                    // Add some random values

                    activePowerTempValue += 0.1;

                    counterValueImport += 1.0;

                    counterValueExport += 0.5;


                    var electricityDevice = GetElectricityDevice(deviceID, activePowerTempValue, counterValueImport, counterValueExport);

          

        // Send to cloud

                    CreateUpdateDevice(electricityDevice);


                });


            });

    </script>


</body>


</html>

Create or update devices

https://smart-me.com/swagger/ui/index 

Heat meter

API Method: 'POST /api/devices'

Info: To create a device don't send a ID.

Payload:

  "Id": "b0ec0030-9f97-4c3c-897f-8175074177bc",

  "Name": "Wärme Zähler Test",

  "Serial": 2233445566,

  "DeviceEnergyType": "MeterTypeHeat", 

  "ActivePower": 5.89,

  "CounterReading": 1234.56, 

}

API Client Library for .Net

To integrate smart-me API functionality into your .Net application you can use this library. It makes HTTP requests to the smart-me REST API. All HTTP request and response bodies are mapped to .Net classes.

Realtime (Webhook) API Example

The smart-me Realtime API sends the data serialized with google protobuffer

Proto File

package RealtimeApi.Containers;

import "bcl.proto"; // schema for protobuf-net's handling of core .NET types


message DeviceData {

   required bcl.Guid DeviceId = 1;

   required bcl.DateTime DateTime = 2;

   repeated DeviceValue DeviceValues = 3;

}

message DeviceDataArray {

   repeated DeviceData DeviceDataItems = 1;

}

message DeviceValue {

   required bytes Obis = 1;

   required double Value = 2;

}

Proto File without BCL

syntax = "proto2";

package com.company;


message TimeSpan {

  required sint64 value = 1; // the size of the timespan (in units of the selected scale)

  optional TimeSpanScale scale = 2; // the scale of the timespan [default = DAYS]

  enum TimeSpanScale {

    DAYS = 0;

    HOURS = 1;

    MINUTES = 2;

    SECONDS = 3;

    MILLISECONDS = 4;

  TICKS = 5;


    MINMAX = 15; // dubious

  }

}


message DateTime {

  optional sint64 value = 1; // the offset (in units of the selected scale) from 1970/01/01

  optional TimeSpanScale scale = 2; // the scale of the timespan [default = DAYS]

  optional DateTimeKind kind = 3; // the kind of date/time being represented [default = UNSPECIFIED]

  enum TimeSpanScale {

    DAYS = 0;

    HOURS = 1;

    MINUTES = 2;

    SECONDS = 3;

    MILLISECONDS = 4;

 TICKS = 5;


    MINMAX = 15; // dubious

  }

  enum DateTimeKind

  {     

     // The time represented is not specified as either local time or Coordinated Universal Time (UTC).

     UNSPECIFIED = 0;

     // The time represented is UTC.

     UTC = 1;

     // The time represented is local time.

     LOCAL = 2;

   }

}


message Guid {

  required fixed64 lo = 1; // the first 8 bytes of the guid (note:crazy-endian)

  required fixed64 hi = 2; // the second 8 bytes of the guid (note:crazy-endian)

}


message DeviceData {

   required Guid DeviceId = 1;

   required DateTime DateTime = 2;

   repeated DeviceValue DeviceValues = 3;

}

message DeviceDataArray {

   repeated DeviceData DeviceDataItems = 1;

}

message DeviceValue {

   required bytes Obis = 1;

   required double Value = 2;

}

Parsing example

Example data

0A5A0A1209E9FCD03B8E9F834111B3D10C1622A22CA1120B08C0C9EAD3A98FE93710051A110A060100010800FF11333333331FAE3C411A110A060100020800FF1100000000000000001A110A060100010700FF11713D0AD7A3303840

Device ID (UUID / GUID)

UUID Data: 0xE9, 0xFC, 0xD0, 0x3B, 0x8E, 0x9F, 0x83, 0x41, 0xB3, 0xD1, 0x0C, 0x16, 0x22, 0xA2, 0x2C, 0xA1

GUID:  3bd0fce9-9f8e-4183-b3d1-0c1622a22ca1

Datetime (UTC)

The Field 1 contains the offset in ticks since 1970-01-01

Seconds since 1970-01-01:  15712284449788512 / 10000000  = 1571228444 (Unix time stamp UTC)

-> 16.10.2019 12:20:44 (UTC)

Device values 

Field 1 contains the OBIS code.  Field 2 contains the value.

01-00-01-08-00-FF:  (1-0:1.8.0*255): Active energy total import: 1879583.2 mWh = 1879.5832 Wh