Endpoint:

You need to make an HTTP POST request to the following URL:

https://api.reengen.com/api/do/

The API expects a valid JSON request in the request body, and returns a JSON response.

All methods with the exception of "Authenticate" must contain the following headers:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

In order to use the API, you first need to get a connection id by calling the Authenticate method. In the JSON request, methods are specified with the $ key. Any additional parameters can be sent under properties.

Methods:

Authenticate

Returns an API connection id if the provided properties tenant, user, and password are correct. \n Request:

Content-Type: application/json

{
"$": "Authenticate",
"properties": {
"tenant": "your tenant name",
"user": "your username",
"password": "your password"
}
}

Response:

{
"properties": { "connectionId": "c04e229f-7d43-4936-823a-30b8f7706ef6" },
"succeeded": true, "message": null, "statistics": {} 
}

properties.connectionId contains your connection id. You can get multiple connection ids if necessary.

GetPointHierarchy

Returns the hierarchy of points (locations) defined in the platform.

Request:

Content-Type: application/json 
XConnectionId: <your connection id> 
XLang: en,<your tenant name>

{ "$": "GetPointHierarchy" }

Response:

{
    "properties": {
        "data": [
            [
                "All",
                {
                    "parent": null,
                    "code": null,
                    "name": null,
                    "id": null
                }
            ],
            [
                "Transformer 6",
                {
                    "parent": "xFabrikaFabrika",
                    "code": "xFabrikaTrafo6",
                    "name": "Transformer 6",
                    "id": 12768,
                    "startingDate": null
                }
            ],
            [
                "Storage",
                {
                    "parent": "xfabrikaImalathane",
                    "code": "xFabrikaDepo",
                    "name": "Storage",
                    "id": 12747,
                    "startingDate": null
                }
            ],
            [
                "Mechanical Workshop",
                {
                    "parent": "xfabrikaArge",
                    "code": "xFabrikademoAtolye",
                    "name": "Mechanical Workshop",
                    "id": 12755,
                    "startingDate": null
                }
            ],
            ...
        ]
    },
    "succeeded": true,
    "message": null,
    "statistics": {}
}

Each entry under properties.data is an array that corresponds to a point. The first element of the array contains the name of the point, and the second element contains an object with the following keys:

  • parent: The code of the point this point is a child of. (string)
  • code: A unique human-readable code identifying the point. (string)
  • name: The name of the point. (string)
  • id: A unique id identifying the point. (integer)

GetData

GetData is the heart of the Reengen Energy IoT Platform API. It allows you to retrieve one or more measurement data stored on one or more points by using aggregate functions. It can also calculate the monetary cost of utility consumption data.

Get Measurement Data

Request:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

{
    "$": "GetData",
    "properties": {
        "series": [
        {
            "definition": "activeEnergy",
            "variant": "import",
            "type": "actual",
            "xFunction": "sum",
            "unit": "kWh",
            "decimalPoints": 2
        },
        {
            "definition": "reactiveEnergy",
            "variant": "import",
            "type": "actual",
            "xFunction": "avg",
            "unit": "VArh",
            "decimalPoints": 2
        }
        ],
        "point": ["xFabrikaTrafo6"],
        "start": "2020-01-20T00:00:00",
        "end": "2020-01-23T23:59:59",
        "break": {
          "type": "point"
        },
        "resolution": "day"
    }
}

series is used to query one or more measurement data by the following criteria:

Criteria Definition
definition The measurement type. Commonly used values are: 'activeEnergy', 'reactiveEnergy', 'capacitiveEnergy', 'inductiveReactiveEnergy', 'activePower', 'voltage', and 'current'. (string)
variant The measurement subtype. Commonly used values are: 'import' for consumption and inductive reactive energy, 'export' for capacitive energy, 'produced' for production, 'phase' for voltage, current, and active power. (string)
type Use 'actual' for actual data. (string)
xFunction Aggregation function. Can be 'sum', 'avg', 'max', or 'min'. (string)
unit The unit for returned results. Commonly used values are: 'kWh', 'Wh' , 'V', 'A', 'kvarh'. (string)
decimalPoints The number of decimal points returned. (integer)

The remaining parameters are:

  • point: null for all points, or an array of point codes for selected points (array | null)
  • start: The start date (string)
  • end: The end date (string)
  • break: (optional) if the type is the point, the returned results will be grouped by point (object)
  • resolution: The resolution for the aggregated data. Can be 'day', 'week', 'month', 'hour', or 'fifteenmin'.

Response:

{
    "properties": {
        "data": {
            "0": [
                [
                    "2020-01-20T00:00:00",
                    12768,
                    2318.14
                ],
                [
                    "2020-01-21T00:00:00",
                    12768,
                    4367.47
                ],
                [
                    "2020-01-22T00:00:00",
                    12768,
                    2541.11
                ],
                [
                    "2020-01-23T00:00:00",
                    12768,
                    2468.10
                ]
            ],
            "1": [
                [
                    "2020-01-20T00:00:00",
                    12768,
                    747.97
                ],
                [
                    "2020-01-21T00:00:00",
                    12768,
                    493.56
                ],
                [
                    "2020-01-22T00:00:00",
                    12768,
                    179.09
                ],
                [
                    "2020-01-23T00:00:00",
                    12768,
                    229.92
                ]
            ]
        },
        "start": "2020-01-20T00:00:00",
        "end": "2020-01-23T23:59:59"
    },
    "succeeded": true,
    "message": null,
    "statistics": {}
}

The properties.data key in the response contains an object with keys starting from 0 for each requested measurement data.

Each key contains an array of measurements for the requested resolution. In turn, each entry in the array is also an array. The first element of the array is the measurement date, the second value is the id of the point, and the third value is the measurement.


Get Cost Data

Request:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

{
    "$": "GetData",
    "properties": {
        "series": [
            {
                "calculator": "cost",
                "type": "actual",
                "selection": "own",
                "utility": "electricity",
                "decimalPoints": 0,
                "group": "activeEnergyCost",
                "includeTax": "None"
            }
        ],
        "point": null,
        "start": "2020-03-01T00:00:00",
        "end": "2020-03-31T23:59:59",
        "break": {
            "type": "point"
        }
    }
}

series is used to query one or more cost data by the following criteria:

Criteria Definition
calculator Use 'cost' for cost calculation (string)
type Use 'actual' for actual data. (string)
selection Use 'own' for own data. (string)
utility Type of utility. Can be 'electricity', 'water', 'gas', or 'medicalGas'. (string)
decimalPoints The number of decimal points returned. (integer)
group Group by filter. Can be 'activeEnergyCost', 'reactiveEnergyCost', 'waterCost', 'gasCost' or 'medicalGasCost'. (string)
includeTax Can be 'None' or 'Internal'. (string)

The remaining parameters are:

  • point: null for all points, or an array of point codes for selected points (array | null)
  • start: The start date (string)
  • end: The end date (string)
  • break: (optional) if the type is the point, the returned results will be grouped by point (object)

Response:

{
    "properties": {
        "data": {
            "0": [
                [
                    10644,
                    235354
                ],
                [
                    10731,
                    264339
                ],
                [
                    11512,
                    168603
                ],
                ...
            ]
        },
        "start": "2020-03-01T00:00:00",
        "end": "2020-03-31T23:59:59"
    },
    "succeeded": true,
    "message": null,
    "statistics": {}
}

The properties.data key in the response contains an object with keys starting from 0 for each requested cost data.

Each key contains an array of costs. In turn, each entry in the array is also an array. The first element of the array is the id of the point, and the second value is the cost.

 

ListDataEx

Returns raw data for requested points and date range.

Request:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

{
    "$": "ListDataEx",
      "properties": {
        "requestType": "code",
        "point": ["xyzBesiktas"],
        "definition": ["activeEnergy"],
        "variant": ["import","export"],
        "type": ["actual"],
        "properties": [ "point.code", "definition.code", "variant.code", "index", "type.code", "date", "definition.unit.code", "value", "original", "note"],
        "start": "2021-02-25T00:00:00",
        "end": "2021-02-25T23:59:59"
    }
}
Criteria Definition
point The id or code for points. (array)
requestType Defines how the properties of the results are returned. Can be 'code' or 'id'. (string)
definition The measurement types for requested data. Commonly used values are: 'activeEnergy', 'reactiveEnergy', 'capacitiveEnergy', 'inductiveReactiveEnergy', 'activePower', 'voltage', and 'current'. (array)
variant The measurement subtypes. Commonly used values are: 'import' for consumption and inductive reactive energy, 'export' for capacitive energy, 'produced' for production, 'phase' for voltage, current, and active power. (array)
type The type of data. Use 'actual' for actual data. (array)
properties The properties to return for the requested data (array)
start The start date (string)
end The end date (string)

Response:

{
    "properties": {
        "data": [{
                "date": "2021-02-25T00:04:59",
                "definition.code": "activeEnergy",
                "note": null,
                "original": 282052078.00,
                "point.code": "xyzBesiktas",
                "index": 1,
                "type.code": "actual",
                "value": 237.00,
                "variant.code": "import",
                "definition.unit.code": "Wh"
            },
            {
                "date": "2021-02-25T00:19:59",
                "definition.code": "activeEnergy",
                "note": null,
                "original": 282052316.00,
                "point.code": "xyzBesiktas",
                "index": 1,
                "type.code": "actual",
                "value": 238.00,
                "variant.code": "import",
                "definition.unit.code": "Wh"
            },
            {
                "date": "2021-02-25T00:39:59",
                "definition.code": "activeEnergy",
                "note": null,
                "original": 282052633.00,
                "point.code": "xyzBesiktas",
                "index": 1,
                "type.code": "actual",
                "value": 317.00,
                "variant.code": "import",
                "definition.unit.code": "Wh"
            }
        ],
        "rowCount": 3
    },
    "succeeded": true,
    "message": null,
    "statistics": {}
}

The properties.data key in the response contains an array of data objects with the requested properties.

ImportData

Import raw data for the requested point.

Request:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

{
  "$": "ImportData",
    "properties": {
        "data": [{
            "point": "reengenPoint",
            "definition": "activeEnergy",
            "variant": "import",
            "index": 1,
            "value": 121,
            "type": "actual",
            "date": "2020-12-23T10:16:26"
        },
         {
            "#": "C",
            "point": "reengenPoint",
            "definition": "activeEnergy",
            "variant": "import",
            "index": 1,
            "value": 121,
            "type": "actual",
            "date": "2020-12-23T10:17:26"
        },
         {
            "#": "D",
            "point": "reengenPoint",
            "definition": "activeEnergy",
            "variant": "import",
            "index": 1,
            "value": 121,
            "type": "actual",
            "date": "2020-12-23T10:17:26"
        }]
}

 

Criteria Definition
point code for point. (string)
# operant for the requested operation values are 'C' for create, 'U' for an update, 'D' for delete (default value is 'C') (string)
definition The measurement type for imported data. Commonly used values are: 'activeEnergy', 'reactiveEnergy', 'capacitiveEnergy', 'inductiveReactiveEnergy', 'activePower', 'voltage', and 'current'. (string)
variant The measurement subtype. Commonly used values are: 'import' for consumption and inductive reactive energy, 'export' for capacitive energy, 'produced' for production, 'phase' for voltage, current, and active power. (string)
type The type of data. Use 'actual' for actual data. (string)
index Index for import data. Some values can have many for a single point such as voltage (number)
date Date (string)
value Value (float)

Response:

{
    "succeeded": true,
    "message": null,
    "statistics": {}
}

The "successed" is true if the command is successful. Otherwise, check the message for errors.

 

GetDCData

Gets raw data from the Data Science table.

Request:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

{
    "$": "GetDCData",
    "properties": {
        "point": ["xyzBesiktas"],
        "type": "test",
        "tenant": "xyz"
     },
     "cache": null
}
  • point: Array of codes for points. (array)
  • type: Type of requested data (string)
  • tenant: Tenant code for requested data type (string)

Response:

{
    "properties": {
        "data": [
            {
                "tenant": "xyz",
                "point": "xyzBesiktas",
                "type": "test",
                "value": "3"
            }
        ]
    },
    "succeeded": true,
    "message": null,
    "statistics": {}
}

The properties.data key in the response contains an array of data objects with the requested value.

ManageDCData

Performs CRUD operations on the Data Science table.

Request:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

{
      "$": "ManageDCData",
      "properties": {
            "data": [{
              "point": "xyzBesiktas",
              "type": "test",
              "tenant": "xyz",
              "value": "3",
              "#": "CU"
        }]
    }
}
  • point: Point codes. (array)
  • type: Data type (string)
  • tenant: Tenant code (string)
  • value: Data value (string)
  • #: Operation to perform: 'C', 'U', 'CU', 'D' (Create | Update | Create or Update | Delete) (string)

Response:

{
    "properties": {
        "data": [
            {
                "tenant": "xyz",
                "point": "xyzBesiktas",
                "type": "test",
                "value": "3"
            }
        ]
    },
    "succeeded": true,
    "message": null,
    "statistics": {}
}

The properties.data key in the response contains an array of data objects with the requested value.

 

ListAvailableCommands

Lists the available remote control commands that can be executed on a point.

Request:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

{
    "$": "ListAvailableCommands",
    "properties": {
        "point": "xFabrikaTrafo6"
    }
}

point is the id or code for a point. (integer | string)

Response:

{
    "properties": {
        "data": [
            {
                "parameterType": "boolean",
                "commandType": "SingleParameter",
                "code": "lights-on-off",
                "name": "Turn Lights On/Off"
            },
            {
                "commandType": "MultiOption",
                "code": "generator-mode-set",
                "name": "Set Generator Mode",
                "options": [
                    {
                        "code": "on",
                        "name": "On"
                    },
                    {
                        "code": "off",
                        "name": "Off"
                    },
                    {
                        "code": "auto",
                        "name": "Auto"
                    }
                ]
            }
        ]
    },
    "succeeded": true,
    "message": null,
    "statistics": {}
}

The properties.data key in the response contains an array of objects that define the available commands.

The commandType can be 'NoParameter', 'SingleParameter' or 'MultiOption'. SingleParameter commands accept a value of the type specified in 'parameterType'. MultiParameter commands accept the 'code' field of one of the options returned in 'options'.

ExecuteCommand

Executes a remote control command on a point.

Request:

Content-Type: application/json
XConnectionId: <your connection id>
XLang: en,<your tenant name>

{
    "$": "ExecuteCommand",
    "properties": {
        "point": "xFabrikaTrafo6",
        "command": "lights-on-off",
        "parameter": true
    }
}

  • point is the id or code for a point. (integer | string)

  • command is the code of the command. (string)

  • parameter is the parameter passed to the command. (any)

     

Success Response:

{
    "properties": {},
    "succeeded": true,
    "statistics": {}
}

Error Response:

{
    "properties": {},
    "succeeded": false,
    "message": "SocketTimeoutException: connect timed out",
    "statistics": {}
}