API

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.

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.

Login to the smart-me portal
Select user at the top right
Settings
API & Access Change

Add oAuth applications

Trusted (Limited to 3 Client ID)
- Client ID and Client secret will be created
Public (Limited to 3 Client ID)
- Client ID is created
Device (Limited to 50 Client ID)
- Client ID and Client secret will be created

Required information

Name
Redirect Urls
Required permissions

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;

}

API - Goldaprtner

To use our API - Goldpartner, you must have the smart-me Goldpartner license model. Further information on this license model can be obtained via the sales department.

Get all devices

Gets all devices assigned to the partner
GET /PartnerAllDevices

Get all devices from one Account

Gets all devices assigned to one of the users assigned to the partner (Get Id with "Get users" )
GET /PartnerAllDevices/{id} - only for one device

Get all device informations

Gets all information for all devices assigned to the partner user or to a sub-user of the partner
GET /PartnerAllDeviceInformations
GET /PartnerAllDeviceInformations/{id} - only for one device

Get fast send device values

Force a device to send the data every second (if supported). This for about 30s

GET /partner/fastsenddevicevalues

Get Folder menu

Gets the folder menu items for a user of a partner

GET /partner/foldermenu/{id}

Update folder menu

Creates and updates the folder menu items for a user. Attention: All existing configuration (folder, billing, export, ...) is deleted!!
POST /partner/foldermenu/{id}

Get users

Get the information about all users of the partner
GET /partner/user

Update user

Updates the email and/or the password of a user. The user must be created by the partner.

POST /partner/user/{id}

Sign up user

Creates a new user and assign it to the partner user
POST /SignUpPartner

Get values in past multiple

Gets multiple values of a device. The device must be installed in an account assigned to your partner account.
GET /partner/ValuesInPastMultiple

Get visualization configuration

Gets the visualization configuration for all folders of a user
GET /partner/visualizationconfiguration/{id}

Update firmware

Update the Firmware (if available) for the given devices
POST /UpdateFirmwarePartner

PartnerVisualization

Gets the visualization configuration for all folders of a user
GET /partner/visualizationconfiguration/{id}

Examples

API examples

REST API Samples

This allows you to pick up any data sets that we provide. https://api.smart-me.com/swagger/index.html

HTML / Javascript (jquery) Examples

Get all devices

<html>

<head>

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

</head>

<body>

<h1>Get all devices</h1>

</ul>

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>

</head>

<body>

<h1>Create and update devices</h1>

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

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

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