Differences

This shows you the differences between two versions of the page.

--- en:mervis-scada:50-api [2017/06/29 10:55]
m.chlupac
+++ en:mervis-scada:50-api [2026/07/17 12:41] (current)
z.moustis
@@ Line 1: / Line 1: @@
-====== API ======
+====== Mervis SCADA API ======
-Mervis SCADA offers open REST API based on JSON and XML data formats. For full description please contact our [[:en:help:support|technical support]].
+Mervis SCADA offers an open, REST-like API based on JSON and XML data formats for seamless integration with third-party applications. For a full description of advanced features, please contact our [[:en:help:20-support|technical support]].
-===== Example =====
+**Important Note on Formatting:** While JSON is heavily utilized in newer endpoints, the only officially supported backward-compatible response format across the entire legacy API is XML.
-**Request: GetHistoryRequest**
+===== Supported API Methods =====
-   * URL: /api/get/history?format=xml
+Below is the consolidated list of recommended API endpoints. Note: Only methods with fully documented and verified examples are listed below.
-<sxh json>
+^ Function ^ Description |
+| **Authentication** | |
+| ''api/v2/get/authenticate'' | Authenticates a user and returns a session token for subsequent API calls. |
+| **Project & Data Structure** | |
+| ''api/get/projects'' | Retrieves a list of all projects accessible to the logged-in user. |
+| ''api/get/projectByParts'' | Retrieves the visual tree structure and the list of datapoints within a specific project. |
+| **Reading Data** | |
+| ''api/get/values'' | Retrieves the current, real-time values of specified datapoints. |
+| ''api/v3/get/history'' | Downloads historical trend data for one or multiple series in a single, paginated call. |
+| ''api/get/history/specific'' | Retrieves specific historical datapoints relative to a provided reference time. |
+| **Writing & Execution** | |
+| ''api/set/values'' | Writes new values to specified datapoints. |
+| ''api/set/executeActions'' | Executes predefined actions or buttons (e.g., INIT, ZAP commands) on datapoints. |
+| ''api/set/history'' | Inserts new historical data values into the database. |
+| ''api/replace/history'' | Completely replaces existing historical data within a specified time range. |
+**Note on Credentials:** You can test these API calls using the credentials `n: demo` and `p: demo`. For production applications, it is required to exchange these credentials for a token using `api/v2/get/authenticate` and use the resulting token (`t: [token_string]`) in subsequent calls to ensure optimal performance.
+===== Authentication =====
+==== api/v2/get/authenticate ====
+**Request:**
+  * **URL:** ''/api/v2/get/authenticate?format=json''
+  * **Method:** POST
+Standard login:
+<code javascript>
+{"data":{"cred":{"n":"demo","p":"demo"}}}
+</code>
+Domain-specific login:
+<code javascript>
+{"data":{"cred":{"d":"GlobalDomain","n":"demo","p":"demo"}}}
+</code>
+**Response Properties:**
+  * **token** (string) - Authentication token for calling other API methods.
+  * **tokenValidFor** (TimeSpan) - The duration for which the provided token is valid (e.g., "P1D" = 1 day).
+  * **changePwdBefore** (DateTime or null) - Specifies the date and time by which the current password must be changed.
+<code javascript>
 {
-   "cred":{
+    "data": {
-      "t":"d1871589-c455-416a-91f3-d9cda3aa5e0f"
+        "ChangePwdBefore": null,
-   },
+        "ClientType": 2,
-   "projId":"2e4deb05-0517-4ef7-ae7a-02e146b23a1d",
+        "Domain": "3c73477a-6c95-4939-b047-7bbf902bcef1",
-   "dpId":"ffb370fc-eeb8-404f-9088-46577ea64134",
+        "DomainName": "GlobalDomain",
-   "providerId":"689E32FA-24A2-448E-9374-6158E6E6CB15",
+        "FullName": "GlobalDomain\\demo",
-   "from":"/Date(1494280800000)/",
+        "Login": "demo",
-   "to":"/Date(1494412488822)/",
+        "NotifyNearingPwdExpirationIn": null,
-   "offset":0,
+        "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f",
-   "count":5000,
+        "TokenValidFor": "P1D",
-   "historyState":""
+        "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e",
+        "Username": ""
+    },
+    "result": { "code": 0, "codeTxt": null, "dataType": null, "desc": null }
 }
-</sxh>
+</code>
+===== Reading Data =====
+==== api/get/values ====
+Retrieves current values of data points (property "Output") from one or multiple projects.
+**Request:**
+  * **URL:** ''/api/get/values?format=xml''
+  * **Method:** POST
 <code javascript>
 {
-   "cred":{
+ "cred": {
-      "t":"d1871589-c455-416a-91f3-d9cda3aa5e0f"
+  "n": "demo",
-   },
+  "p": "demo"
-   "projId":"2e4deb05-0517-4ef7-ae7a-02e146b23a1d",
+ },
-   "dpId":"ffb370fc-eeb8-404f-9088-46577ea64134",
+ "propNamesToSerialize": ["Output"],
-   "providerId":"689E32FA-24A2-448E-9374-6158E6E6CB15",
+ "offset": 0,
-   "from":"/Date(1494280800000)/",
+ "count": 1000,
-   "to":"/Date(1494412488822)/",
+ "serverState": null,
-   "offset":0,
+ "dps": [{
-   "count":5000,
+   "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
-   "historyState":""
+   "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
+  }]
 }
 </code>
-**Response**
+**Response:**
+<code xml>
+<?xml version="1.0" encoding="utf-8"?>
+<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2026-07-17T10:29:17Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints">
+ <vals>
+  <v projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" serverTime="2026-07-17T10:29:17Z">
+   <dps>
+    <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" serAlr="true">
+     <props>
+      <p n="Output" t="2026-07-17T10:29:17Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55">
+       <n1:v>13851.42</n1:v>
+      </p>
+     </props>
+    </d>
+   </dps>
+  </v>
+ </vals>
+</values>
+</code>
+==== api/v3/get/history ====
+Downloading one or multiple trends with a single API call.
+**Rules:**
+  * Items "segmentation", "requestState", and "serverState" should always copy the values from the last server response for pagination. The first call should use an empty "segmentation".
+**Request:**
+  * **URL:** ''/api/v3/get/history?format=json''
+  * **Method:** POST
+<code javascript>
+{
+    "credentials": {
+        "name": "demo",
+        "password": "demo"
+    },
+    "request": {
+        "commonSeriesParameters": {
+            "from": "2026-06-20T00:00:00Z",
+            "to": "2026-07-17T00:00:00Z"
+        },
+        "series": [
+            {
+                "clientReference": "test1",
+                "provider": {
+                    "parameters": {
+                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
+                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
+                    }
+                }
+            }
+        ]
+    },
+    "dataSpecification": {
+        "limits": { "count": 1000 }
+    },
+    "segmentation": {
+        "requestState": "",
+        "serverState": ""
+    }
+}
+</code>
+**Response Details:**
+  * **v** - value
+  * **ts** - timestamp (start of validity period)
+  * **gt** - goodthrough (end of validity period)
+  * **meta.interval** - expected interval between stored records. Useful to identify missing data.
+<code javascript>
+{
+    "result": { "code": 0, "subCode": 0, "message": "" },
+    "data": {
+        "count": 1,
+        "historyData": [
+            {
+                "clientReference": "test1",
+                "provider": {
+                    "id": "689e32fa-24a2-448e-9374-6158e6e6cb15",
+                    "parameters": {
+                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
+                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
+                    }
+                },
+                "meta": { "type": "double", "unit": "h", "interval": "PT3M" },
+                "values": [
+                    { "v": 13851.4, "ts": "2026-06-25T12:00:00.000Z" }
+                ]
+            }
+        ]
+    },
+    "segmentation": { "requestState": "", "serverState": "" }
+}
+</code>
+==== api/get/history/specific ====
+**Request:**
+  * **URL:** ''/api/get/history/specific?format=json''
+  * **Method:** POST
+  * **dataSpec:** Defines the specific point to fetch (e.g., 2 = First value less than reference time).
+  * **refTime:** Reference time required for specific temporal searches.
+<code javascript>
+{
+ "cred": {
+  "n": "demo",
+  "p": "demo"
+ },
+ "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
+ "offset": 0,
+ "count": 1000,
+ "dataSpec": 2,
+ "refTime": "\/Date(1692788459000)\/",
+ "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
+}
+</code>
+===== Writing Data & Execution =====
+==== api/set/values ====
+**Request:**
+  * **URL:** ''/api/set/values?format=xml''
+  * **Method:** POST
 <code xml>
-<getHistoryResult xmlns:r="http://dev.rcware.eu/serialization/references" r:type="b133774d-21ce-42b6-add3-57c012079c55" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/history">
+<?xml version="1.0" encoding="UTF-8"?>
-    <hist projId="2e4deb05-0517-4ef7-ae7a-02e146b23a1d" dpId="ffb370fc-eeb8-404f-9088-46577ea64134" propName="Output" interval="PT5M" historyState="" nextValOfs="-1">
+<setValuesRequest xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/datapoints" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/comm-props" >
-        <errMsg/>
+   <n2:cred n="demo" p="demo"/>
-        <vals>
+        <values projId="1b2623be-eaa4-4e29-8596-c66dd85d5643">
-            <hv ts="2017-05-08T22:26:53.32684Z" gt="2017-05-08T22:31:53.465467Z">
+            <dps>
-                <n1:v>4.3</n1:v>
+                <d id="07d538d9-9f4b-46ca-ba4d-13b13b5302ff">
-            </hv>
+                    <props>
-            <hv ts="2017-05-08T22:36:53.283875Z">
+                        <p n="Source" t="2024-02-23T09:58:00Z" r:type="1c104bdf-ffcb-4c90-b491-e4781a91ef09">
-                <n1:v>4.2</n1:v>
+                            <n1:v>23</n1:v>
-            </hv>
+                        </p>
-            <hv ts="2017-05-08T22:41:53.435042Z">
+                    </props>
-                <n1:v>4.1</n1:v>
+                </d>
-            </hv>
+            </dps>
-            <hv ts="2017-05-08T22:46:53.711496Z" gt="2017-05-08T23:36:53.776657Z">
+        </values>
-                <n1:v>4</n1:v>
+</setValuesRequest>
-            </hv>
+</code>
-        </vals>
+==== api/set/executeActions ====
-    </hist>
+**Request:**
-</getHistoryResult>
+  * **URL:** ''/api/set/executeActions?format=xml''
+  * **Method:** POST
+<code xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs" xmlns:n2="http://dev.rcware.eu/scada/basic-props" xmlns:n1="http://dev.rcware.eu/auth" xmlns:r="http://dev.rcware.eu/serialization/references">
+  <n1:cred n="demo" p="demo"/>
+  <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0">
+    <actions>
+      <actionDefItem propName="INIT" dpId="afc22e18-f8e4-4e08-899c-fb9e4759df3d">
+        <execParam r:type="495c9644-eed1-4b94-933b-3fae702a9aca">
+          <n2:value>16</n2:value>
+        </execParam>
+      </actionDefItem>
+      <actionDefItem propName="ZAP" dpId="34306c80-73f1-4465-ab51-2b2c1e85ab70">
+      </actionDefItem>
+    </actions>
+  </actionDefs>
+</executeActionsRequest>
 </code>
+==== api/set/history & api/replace/history ====
+Attribute **i** sets **interval** (ISO 8601) in which the next value should be expected. All date/time values must be in UTC.
+**Replace History Request Example:**
+  * **URL:** ''/api/replace/history?format=xml''
+  * **Method:** POST
+<code xml>
+<?xml version="1.0" encoding="UTF-8"?>
+<replaceHistoryRequest xmlns="http://dev.rcware.eu/scada/history" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/basic-props" projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="e86dba6d-1250-4e7f-aafb-84fd28324710" from="2020-03-15T11:00:00+00:00" to="2020-03-18T11:00:00+00:00">
+  <n2:cred n="demo" p="demo"/>
+  <vals>
+    <hv ts="2020-03-15T11:00:00+00:00" i="P1D">
+      <n1:v>2.7</n1:v>
+    </hv>
+    <hv ts="2020-03-16T11:00:00+00:00" i="P1D">
+      <n1:v>3.0</n1:v>
+    </hv>
+  </vals>
+</replaceHistoryRequest>
+</code>
+===== Projects Management =====
+==== api/get/projects ====
+**Request:**
+  * **URL:** ''/api/get/projects?format=xml''
+  * **Method:** POST
+<code javascript>
+{
+ "cred": {
+  "n": "demo",
+  "p": "demo"
+ },
+ "offset": 0,
+ "count": 250
+}
+</code>
+**Response:**
+<code xml>
+<?xml version="1.0" encoding="utf-8"?>
+<getProjectsResult xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/projects">
+    <projects>
+        <project id="2a7f1615-..." name="Weather" />
+        <project id="1b2623be-eaa4-4e29-8596-c66dd85d5643" name="SIMPLE_DEMO" />
+        <project id="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" name="PLYNOVA_KOTELNA" />
+        <project id="b9ad5380-..." name="CVUT_HERBERTOV" />
+        <project id="843855a2-..." name="PRVNI_KROKY" />
+    </projects>
+</getProjectsResult>
+</code>
+==== api/get/projectByParts ====
+To get the visual tree and list of datapoints.
+**Request:**
+  * **URL:** ''/api/get/projectByParts?format=xml''
+  * **Method:** POST
+<code javascript>
+{
+ "cred": {
+  "n": "demo",
+  "p": "demo"
+ },
+ "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
+ "treeId": "Visual tree",
+ "partType": 0,
+ "offset": 0,
+ "count": 250
+}
+</code>
+===== Matlab Client =====
+==== General Notes ====
+  * Parameter names **ID** and **Guid** are used interchangeably in the Matlab client; it is always a universally unique identifier referring to a project or datapoint.
+  * When plural is used, an array of guids is expected (ie. ''{'guid1', 'guid2'}'' ), otherwise just one guid is expected.
+==== ScadaClient ====
+<code matlab>ScadaClient(url, username, password)</code>
+Constructor of the Mervis API wrapper.
+==== findAllDPsWithReqTags ====
+<code matlab>findAllDPsWithReqTags(projIds, tags)</code>
+Returns list of datapoints based on tags query. Example of tags definition: ''{'label','indoor_air_temperature';'room_type','office'}''
+==== getDpTags ====
+<code matlab>getDpTags(projectId, DpId)</code>
+Returns tags of the particular datapoint.
+==== getAllProjectDPs ====
+<code matlab>getAllProjectDPs(projectGuid)</code>
+Returns project IDs and names that are accessible to the logged-in user.
+==== getData ====
+<code matlab>[data, time, dataInCell, info] = getData(projID, dpsIds, from, to, span, zone, doublesInterpolationMethod, interpolate_gaps_shorter_than)</code>
+Downloads data.
+  * **span:** sampling interval in seconds, default is 300 sec.
+  * **zone:** time zone ('local' or 'utc') applied to parameters and output, default is 'local'.
+  * **Returns:** ''data'' (NaN used for missing values), ''time'', ''dataInCell'' (useful for strings), and ''info''.
+**Data Download Example:**
+<code matlab>
+scada = ScadaClient('https://scada.mervis.info/','demo','demo');
+dataPointIDs = {'acad79f3-3358-42dd-9b74-98733e63d771','1afa7d9b-1183-4ab1-a6b1-18e464ae2d4d','e496bb8c-14ce-4c2c-b53b-3b71daeabca6'};
+projectId = '5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0';
+chartLegend = {'Temp UT1','Temp UT1 Return','Valve Position'};
+from = now - 4;
+to = now;
+timeSpan = 300; %sec
+[data, time] = scada.getData(projectId, dataPointIDs, from, to, timeSpan);
+plot(time,data);
+legend(chartLegend);
+datetick;
+</code>
+==== saveData ====
+<code matlab>saveData(projID, dpID, time, data)</code>
+Saves data into the Mervis database.
+==== setDataPointValue ====
+<code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code>
+Sets a datapoint value using a button. Only numerical values are supported. Parameter ''buttonName'' is not mandatory; 'INIT' is used if undefined.
+**Example:**
+<code matlab>
+dpGuid = 'ccaacb77-295b-48a8-a712-3fb272aa9b6f';
+projectId = '6b65447e-8622-4a0d-b3b9-42f1d905fdaa';
+buttonName = 'INIT';
+newValue = 1;
+scada = ScadaClient('https://scada.mervis.info/','demo','demo');
+scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)
+</code>
+==== deleteVariable ====
+<code matlab>deleteVariable(projGuid, dpGuid, from, to)</code>
+**Warning:** Deletes data of one variable based on from-to interval. If from-to is not defined, ALL data are deleted. Use carefully, there is no undo!