API

Introduction

API usage requires at minimum three parameters:

• Base URL
  Address of the server to send API requests to. For the Cloud, use the following base URL:
  https://energymachines.cloud/api/v1/

• Access token
  Cloud API uses bearer authorization, which relies on a single string, referred to as access token, to authenticate the user. Contact EnergyMachines™ support to get an appropriate access token.

  Tokens provide fine-grained access to specific projects/project data as configured when creating a token. API requests may result in an error if the token does not have sufficient access to retrieve the requested data.

• Endpoint
  String appended to the base URL to specifically request particular data as discussed below. Base URL and endpoint together form the request body.

Basic syntax

This section demonstrates basic use of the Cloud API with the popular API library Python Requests.

Cloud API uses two request types:

requests are submitted with requests.get:

# prepare the requests lib
pip install requests # unless already installed
import requests

# main API parameters
baseurl = "https://energymachines.cloud/api/v1/"
token = "%YOUR_ACCESS_TOKEN%" # Refer to EM customer support
headers = { "Authorization": f'Bearer {token}' }

# request variables
pid = "%PROJECT_ID%" # Target project ID
params = { "tagPath": "%PATH/TO/TAG%"} # Query parameters

endpoint = f'{pid}/tag/by-path' # Endpoint with a URL parameter

# request
request = baseurl + endpoint # concatenate two strings to get the appropriate request URL
response = requests.get(request, headers = headers, params = params).json()

This example demonstrates a tag by path request.

requests are submitted with requests.post and must be accompanied with a request body in the JSON format; see Parameters below:

# prepare the requests lib
pip install requests # unless already installed
import requests

# main API parameters
baseurl = "https://energymachines.cloud/api/v1/"
token = "%YOUR_ACCESS_TOKEN%" # Refer to EM customer support
headers = { "Authorization": f'Bearer {token}' }

# request variables
pid = "%PROJECT_ID%" # Target project ID
data = { "accessMode": "R", "devicePathList" : ["Signals/DEVICE_01/"]} # Request body

endpoint = f'{pid}/tag/values/export/csv' # Endpoint with a URL parameter

# request
request = baseurl + endpoint # concatenate two strings to get the appropriate request URL
response = requests.get(request, headers = headers, json=data).text

This example demonstrates a tag value export request.

TIP

Use method json() if the endpoint returns a JSON, or the text property if the endpoint returns a CSV; see examples above.

Request type is specified for each endpoint below.

Parameters

Cloud API uses the following types of request parameters:

URL parameters

Variables that are substituted into the endpoint string:

variable = "%some_string_value%"
endpoint = f'url/{variable}'

Cloud API has only four URL parameters and uses them across multiple endpoints:

• projectId — Target project ID, can be retrieved using the project list endpoint, among other means.
• tagId — Target tag ID, can be retrieved using the tag list endpoint, among other means.
• fileId — Target page ID, can be retrieved using the Tags endpoint, among other means.
• format — Format for tag history export using the Tag History Requests endpoints; only has two possible values.
  • json for export in JSON format;
  • csv for export as a plain-text file containing comma-separated values.

URL parameters are used with both and requests.

Query parameters

Variables passed in dictionary, hash, or another object that can hold key-value pairs, and submitted as query parameters using the API library’s appropriate method:

query = { "key" : "value" }
requests.get(... params=query).json()

Cloud API uses only one query parameter:

• tagPath — Tag path for use with tag by path and tag value by path; can be retrieved using the tag list endpoint, among other means.

Query parameters are only used with requests.

Request body parameters

Variables passed in a dictionary, hash, or similar object that can hold key-value pairs; submitted as a JSON object in the request body.

request_body = { "key": "value" }
requests.post(... json=request_body).json()

Request body parameters are only used with requests. Cloud API has three endpoints:

• tag value export
• Tag History Requests (contains two endpoints).

Request body specifications are provided below in endpoint descriptions, which are structured as follows:

endpoint description

TYPE endpoint/with/{urlParams}

Description of data to be returned on such request. Required query parameters, if applicable.

• Request body ( requests only):

  { "key" : "value" // request body parameters }
  

  Comments on the request body and its parameters.

• CODE 200
  Response format on a successfully processed API request:

  { //
    "variable" : "value" // Explanation
  }
  

  for JSON response; or

  String response
  

  for string response, with additional commentary. Other response formats are covered individually.

• CODE 404 (where applicable)
  Response on request failure due to incorrect URL parameters.

  Code 404 error message (string)
  

  Possible causes.

• CODE 500 (where applicable)
  Response on request failure due to insufficient authorization or incorrect request body or query parameters.

  {
    "status": "fail"
    "error": "HTTP 403 Forbidden"
  }
  

  Comments on error message codes.

URL parameters are curly-braced ({parameter}) in the endpoint syntax; however, the actual endpoint string must contain them without braces. Neither URL parameters nor query parameters are covered per endpoint. For details on parameters, see Parameters.

The following endpoints are available:

Project Requests

project list

projects/list

Returns an array of the projects the token is authorized to access.

• CODE 200

  [
    {
      "id": "string", // Project ID
      "name": "string", // Project name
      "types": null // See Project by ID below
    }
    {
      ...
    }
    ...
  ]
  

project by ID

{projectId}/project

Returns data on a specific project.

• CODE 200
  

  {
    "id": "string", // Project ID
    "name": "string", // Project name
    "types": [
      {
        "id": "string", // Project group ID (if the project is in a group)
        "name": "string", // Project group name
        "kpiList": [ // List of KPIs and their data
          {
            "id": "string",
            "name": "string",
            "unit": "string",
            "clusteringFunction": "sum,average,none",
            "isMain": true,
            "isDigital": true,
            "tagId": "string",
          },
        ],
      },
    ],
  }
  

• CODE 404

  Project not found
  

  Project with the provided projectId does not exist.

• CODE 500

  {
    "status": "fail"
    "error": "HTTP 403 Forbidden"
  }
  

  Token is not authorized to access the project with the provided projectId.

Tag Requests

For details on tag paths, see Tags. For details on writability and units, see Tag Editor. Tag names are non-custom names, see tag naming.

tag list

{projectId}/tag/list

Returns an array of the tags in the project with the provided projectId, along with some tag data.

• CODE 200

  [
    {
      "id": "string", // Tag ID
      "name": "string", // Tag name (not custom!)
      "path": "string", // Path to the tag, inclusive of name
      "isWritable": true, // Boolean value: true if tag is writable, false otherwise
      "unit": "string" // Displayable unit for the tag
    }
    {
      ...
    }
    ...
  ]
  

tag by ID

{projectId}/tag/by-id/{tagId}

Returns data on a specific tag.

• CODE 200

  {
    "id": "string",
    "name": "string",
    "path": "string",
    "isWritable": true,
    "unit": "string"
  }
  

  Single-tag JSON, see tag list for comments on key-value pairs.

• CODE 404

  Tag not found
  

  Tag with the provided tagId does not exist.

• CODE 500
  

  {
    "status": "fail"
    "error": "HTTP 403 Forbidden"
  }
  

  Token is not authorized to access the project with the provided projectId or to read tags in it.

tag by path

{projectId}/tag/by-path

Returns data on a specific tag; requires query parameter tagPath for identification.

• CODE 200

  {
    "id": "string",
    "name": "string",
    "path": "string",
    "isWritable": true,
    "unit": "string"
  }
  

  Single-tag JSON, see tag list for comments on key-value pairs.

• CODE 404

  Tag not found
  

  Tag with the provided tagPath does not exist.

tag list with values

{projectId}/tag/values/list

Returns an array of the tags in the project with the provided projectId, along with tag values.

• CODE 200

  [
    {
      "id": "0bd8cb60b9f411ee9f950242ac120009", // tag ID
      "value": {
        "error": false, // shows if the tag works correctly; true if the tag throws an error
        "data": 0 // value at the time of the API request: scalar or array
        },
      }
    {
      ...
    }
    ...
  ]
  

tag value by ID

{projectId}/tag/values/by-id/{tagId}

Returns the value of a specific tag.

• CODE 200

  {
    "id": "0bd633dfb9f411ee9f950242ac120009",
    "value": {
      "error": false,
      "data": 0
    }
  }
  

  Single-tag JSON, see tag list for comments on key-value pairs.

• CODE 404

  Tag not found
  

  Tag with the provided tagPath does not exist.

tag value by path

{projectId}/tag/values/by-path

Returns the value of a specific tag; requires query parameter tagPath for identification.

• CODE 200

  {
    "id": "0bd633dfb9f411ee9f950242ac120009",
    "value": {
      "error": false,
      "data": 0
    }
  }
  

  Single-tag JSON, see tag list for comments on key-value pairs.

• CODE 404

  Tag not found
  

  Tag with the provided tagPath does not exist.

tag value export

{projectId}/tag/values/export/csv

Returns the current value(s) of the selected tag(s).

• Request body

  {
    "accessMode" : "R", // tag writability filter
    "devicePathList": [
      "Signals/path/to/device/" // an array of tag paths
    ]
  }
  

  • accessMode selectively samples tags based on their writability and can take either of the two values:
    • R for read-only tags;
    • RW for writable tags.
  • Paths in the devicePathList array must be preceded with the prefix Signals/, for example: Signals/DEVICE_01.
  • Paths are not limited to devices and may also link to folders, see Tags for the tag hierarchy structure. To retrieve all tags from the root level down, provide Signals/ as the solitary path under devicePathList.
• CODE 200

  Tag Name,Tag Value
  Signals/path/to/tag/name/name,current_value
  

  Returns plain text (.txt) containing comma-separated values in two columns:

  • Tag Name — Full path to the tag, starting with the Signals/ prefix.
  • Tag Value — Tag value at the time of response generation.

Tag History Requests

For tag IDs and tag paths, see Tags and Tag Requests. For {format}, see Parameters.

History can be requested via either of the two endpoints below; both provide identical output but require different input in the request body.

tag history by ID

{projectId}/history/aggregate/by-id/{format}

tag history by path

{projectId}/history/aggregate/by-path/{format}

Returns the history of the selected tag(s), if available.

• Request body

  {
    "groupingType": "MINUTES", // periods for averaging
    "valueType": "ACTUAL", // value type, optional
    "tagList": [
      "Device/Tag", // path to tag OR tag ID
      "Folder/Tag",
    ],
    "timeFrom": 1572548400000, // history sampling start time
    "timeTo": 1574239662847    // history sampling end time
    "timeZone": "Europe/Stockholm" // time zone, optional
  }
  

  • groupingType — Value averaging timespan; accepted values are: MINUTES, HOURS, DAYS, MONTHS, YEARS. Default MINUTES returns data where each value is the average of all historical data points collected over a single minute, with the number of values matching the requested timeframe duration in minutes.
  • valueType (optional) — Determines the value calculation principle:
    • ACTUAL (default) returns actual values as grouped (averaged) by the period specified in groupingType;
    • DELTA replaces each value with the difference between it and the preceding value in the set.
  • tagList — Array of string representing tags for history export:
    • use tag ID with {projectId}/history/aggregate/by-id/{format};
    • use tag path with `{projectId}/history/aggregate/by-path/{format}.
  • timeFrom — Unix epoch timestamp, in milliseconds, for the starting point of the requested history sample.
  • timeTo — Unix epoch timestamp, in milliseconds, for the ending point of the requested history sample.
  • timeZone — (optional) Timezone to convert timestamps to, defaults to Europe/London. For list of available time zones, see Available Timezones.
• CODE 200
  If json was requested:

  [
    {
      "tagId" : "string", // See comments below
      "name": "string", //
      "unit": "string", //
      "points": [ // Array of history data points
        {
          "time": integer //
          "value": float //
        }
        ...
      ]
    }
    ...
  ]
  

  If csv was requested:

  time,id,value,name,unit
  %TIMESTAMP%,%TAG_ID%,%TAG_VALUE%,%PATH/TO/TAG%,%TAG_UNIT%
  

  where:

  • time — Unix epoch timestamp of the datapoint, in ms.
  • tagId or id — ID of the processed tag.
  • name — tag path, inclusive of name (not custom).
  • unit — Displayed unit of the tag, if specified in the Tag Editor.
  • value — Tag value at the timestamp. In JSON response, unit and value parameters are grouped into the points array for each tag.

  Timestamps in the response apply to value groups and thus may not correspond to the timestamps of any actual recorded data points. Timestamps for "groupingType":"DAYS" are matched to 00:00 GMT of the actual day in which the values were grouped.

• CODE 500

  {
    "status": "fail",
    "message" : "string" // See error messages below
  }
  

  See error message text for possible causes:

  • HTTP 404 Not Found — Incorrect format; accepted values are csv and json.
  • HTTP 403 Forbidden — Token is not authorized to access the project with the provided projectId or to read its tag history data.
  • Lack of an error message may indicate:
    • incorrect projectId; OR
    • incorrect tag IDs or paths in the request body.

Page Requests

page tree

{projectId}/page/tree

Returns data on all pages in the project hierarchically.

• CODE 200

  {
    "id": "string",
    "projectId": "string",
    "parentId": "string", // or null
    "userId": "string", // null
    "name": "Pages",
    "type": "PAGES_ROOT", // "FOLDER", "PAGE"
    // other metadata
    "children": [
      {
        // metadata
      },
      ...
    }
  ...
  

  Set of metadata on page entities listed in hierarchically descendent order:

  • PAGES_ROOT has no parentId or userId, represents the full list of pages in the project;
  • children of PAGES_ROOT may include FOLDERs and PAGEs;
  • children of a FOLDER may include PAGEs. Each entity has an id that can be used as fileId with page by ID and page stream by ID.

  For space considerations, this article omits a detailed description of the page tree JSON; consult the Swagger specification to find out more!

• CODE 500

  {
    "status": "fail",
    "message": "HTTP 403 Forbidden"
  }
  

  Token is not authorized to access the project with the provided projectId or to read pages in it.

page by ID

{projectId}/page/{fileId}

Returns the content of a specific page in SVG format (plain text).

• CODE 200

  <svg data-root="true" xmlns="http://www.w3.org/2000/svg" ...>...</svg>
  

• CODE 500

  {
    "status": "fail",
    "message": "HTTP 403 Forbidden"
  }
  

  Two possible causes:

  • token is not authorized to access the project with the provided projectId or to read pages in it; OR
  • incorrect fileId.

page stream by ID

{projectId}/page/{fileId}/stream

Returns the content of a specific page in SVG format, as a stream.

• CODE 200

  <svg data-root="true" xmlns="http://www.w3.org/2000/svg" ...>...</svg>
  

  Make sure the API handler is configured to receive stream response; for example:

  requests.get(f'{projectId}/page/{fileId}/stream', stream=True).raw
  

  With Python, the general recommendation would be to use iter_content.

• CODE 500
  See page by ID above.

Available Timezones

timezone/available

Returns the list of all available time zones. Values from the list can be used, e.g., with Tag History Requests.

• CODE 200

  [
    "Africa/Abidjan (UTC+00:00)",
    ...
    "Zulu (UTC+00:00)"
  ]
  

  For use in tag history requests, omit the timezone modifier (in parentheses).