NAV
shell

LineMetrics API (v2)

Welcome to the LineMetrics REST API documentation. The LineMetrics API will enable you to access the basic functions of the LineMetrics Cloud. These include, among others, query of existing streams and saving of data in a configured datastream.

Currently, trial sample codes are only available for the Unix-command line (Shell). Step by step we plan to expand the availability of our trial sample codes to other programing languages. Your cooperation in this regard will be highly appreciated.

The current version of the API is version 2, whereas it has to be mentioned that the current version is still in development. However, existing endpoints should not be changed anymore and further endpoints will be continuously added. The versioning shall allow to create a seamless adaptation of existing endpoints, without influencing the downward compatibility.

Authentication

The current version of the REST API documentation supports an authentication using client-credentials and password-grant via the OAuth2 protocol. Therefore, a session token has to be created via a REST call and the authentication-dependent parameters. Using this session token, you can query other resources (data/objects/resources).

OAuth2 (Client Credentials)

Authentication via OAuth & Client-Credentials

curl "https://lm3api.linemetrics.com/oauth/access_token"
  -d 'client_id={{CLIENT_ID}}&grant_type=client_credentials&client_secret={{CLIENT_SECRET}}'
  -X POST

Response from server

{
    "access_token": "{{key}}",
    "token_type": "Bearer",
    "expires_in": 3600
}

Client Credentials is a type of authentication that should commonly be used. Client Credentials enables the access to all data of the account using the authentication via the parameter Client ID and Client Secret.

Parameter

Parameter Description
client_id ID that clearly identifies the access.
client_secret Client secret, which authorizes the access via Client ID and allows to create a new session token.

Response

Parameter Description
access_token Session token used for queries on API resources and transferred via header.
token_type Defines the type of session token and is indicated as a prefix in the header.
expires_in Time until expiration in seconds

OAuth2 (Password grant)

Authentication via OAuth & Passwort-Grant

curl "https://lm3api.linemetrics.com/oauth/access_token"
  -d 'client_id={{CLIENT_ID}}&grant_type=password& // KEIN ZEILENUMBRUCH
      client_secret={{CLIENT_SECRET}}&email={{EMAIL}}&password={{PASSWORD}}'
  -X POST

Response from server

{
    "access_token": "{{key}}",
    "token_type": "Bearer",
    "expires_in": 3600
}

For the password grant the authentication is done through the parameter Client ID and Client Secret, as usual. Additionally, the parameter E-Mail and Password must be transmitted. Consequently, a token will be generated, which is valid only for this account. For this type of authentication you have to apply at support@linemetrics.com

Parameter

Parameter Description
client_id ID that clearly identifies the access
client_secret Client secret, which authorizes the access via Client ID and allows to create a new session token
email E-mail of the user, who wants to be authorized
password Password of the user, who wants to be authorized

Response

Parameter Description
access_token Session token used for request on API resources and transferred via header.
token_type Defines the type of session token and is indicated as a prefix in the header.
expires_in Time until expiration in seconds

Datatypes

Data types are an essential part when working with data within the LineMetrics Cloud or when working with the REST API, because through data types it can determined, how the particular data should look like and which characteristics a single data point should have.

You obtain data types when querying Inputs available for the API endpoint, or when querying specific datastream of an object.

Double

{
  "val" : 123.0
}

Simple datatype, that only encapsulates a primitive double datatype.

Parameter Prim. Datentype Description
val Double value

DoubleAverage

{
  "val" : 123.3,
  "min" : 10.0,
  "max" : 456.12
}

Datatype that delivers the average value as well as thresholds (min/max)

Parameter Prim. Datatype Description
val Double average
min Double minimum value
max Double maximum value

Bool

{
  "val" : 0
}

Simple datatype, that only encapsulates a primitive bool datatype.

Parameter Prim. Datatyp Description
val Boolean Boolean value 0 or 1

GeoCoord

{
  "lat" : 48.20863000,
  "long" : 16.39741000
}

Datatype, that encapsulates geo-coordinates in form of a longitudinal and a latitudinal value.

Parameter Prim. Datatyp Description
lat Double Latitudinal GPS value (geographic latitude)
long Double Longitudinal GPS value (geographic longitude)

String

{
  "val" : "my text"
}

Simple datatype, that only encapsulates a primitive String datatype.

Parameter Prim. Datatyp Description
val String text

Timestamp

{
  "val" : 1325376000000
}

Datatype, that encapsulates a Long datatype and shows a UTC-timestamp/date within milliseconds.

Parameter Prim. Datatyp Description
val Long UTC timestamp in milliseconds

Table

{
  "val" :
  {
      "column1" :
      { 
        "val" : "Order 96"
      },
      "column2" :
      {
        "val" : 1464608700000
      },
      "column3" :
      {
        "lat" : 1.5877383,
        "long" : 2.0317383
      },
      "column4" :
      {
        "val": 1
      }
  }
}

The datatype Table encapsulates a complex data type that is presented as “table” inside our web application. For this purpose, the user has to define columns inside the application. These columns have a data type that differs from the ones listed above, and a key. The key is used when writing values (e.g. with the API) to uniquely address the individual column values.

For the example, a new measuring point “table” was created in the application. At the measuring point page a column “order number” was created, with a columny key column1, and data type ‘String’, etc.

Parameter Prim. Datatyp Description
val JSON Complex data type that holds one or more data types that mentioned above.

Addressing

The LineMetrics API provides different options to access data or assets and their related datastream/characteristics. In the following section these options will be further explained.

Asset

An asset is a container that encapsulates datastream/characteristics. An asset depicts a real physical object (e.g. a machine, a building, etc). An asset can always be addressed using an UID (see below). Additionally, it is possible to provide a Custom Key for the asset. The custom key is freely selectable, but has to be distinct within the account.

Datastream/Property

A datastream/property is the occurrence of an asset and illustrates the current state (as a value or as time series) or the property of an asset (e.g. how big is my building?) This type of information can be directly addressed using an UID - like an asset. Simultaneously, there is the possibility to deposit a so-called Alias. This is also freely selectable and has to be distinct within the account. Using Custom Key and Alias users can query for data in the following way: Machine1.Occupancy rate -> show me the occupancy rate of machine 1

UID

An UID is a construct of 32 consecutive characters and numbers and represents a distinct ID. Nearly every function enable the addressing of a resource via the UID.

Data resources

Query datatype

Query datatype

curl "https://lm3api.linemetrics.com/v2/data/{{CUSTOM_KEY}}/{{ALIAS}}/config"
  -H "Authorization: Bearer {{KEY}}"

Response from server

  {
    "input": "{{DATATYPE}}",
    "output": "{{DATATYPE}}"
  }

If data should be written on a datastream/property or if data should be read from them, it is necessary to include your own experience in regards to which datatype is used.

This can be determined by using the following commands.

Parameter

Parameter Description
custom_key Addressing of assets Definition
alias Addressing of datastream/property Definition

Response

Parameter Description
input Datatype, that must be used for writing
output Datatype, that is transmitted when reading

Write data

Saving of values

curl "https://lm3api.linemetrics.com/v2/data/{{CUSTOM_KEY}}/{{ALIAS}}"
  -X POST
  -H "Authorization: Bearer {{KEY}}"
  -d "
  [
      {
        "min" : 0.234,
        "val" : 1.678,
        "max" : 6.890
      }
  ]
  "

Response from server

[
  {
    "response": "Success"
  }
]

In order to save new values, a list of elements has to be transferred which represents one datastream at a time that you want to save. If you only want to save a single value, you will transfer a list with a single element. If the saving process fails, please check the HTTP status and the saving status.

Parameter

Parameter Description
custom_key Addressing of the assets Definition
alias Addressing of the datastream/property Definition
data_payload The actual data of the datastream. Dependent from the datatype Definition

Response

Parameter Description
response Status, that determines whether a value was saved.

HTTP Status

Status Description
2*, 3* Saving process successful
400 Wrong JSON structure/ formatting / missing data
500 Internal error while saving. Please mail to support@linemetrics.com

Saving of data(Key - Value)

curl "https://lm3api.linemetrics.com/v2/data/{{CUSTOM_KEY}}/{{ALIAS}}"
  -X POST
  -H "Authorization: Bearer {{KEY}}"
  -d "
  {
      "custom_key" : {
        "min" : 0.234,
        "val" : 1.678,
        "max" : 6.890
      }
  }
  "

Response from server

{
  "custom key" : {
    "response": "Success"
  }
}

Read data (last value)

reading of data

curl "https://lm3api.linemetrics.com/v2/data/{{CUSTOM_KEY}}/{{ALIAS}}?function=last_value"
  -H "Authorization: Bearer {{key}}"

Response from server

[
  {
    "min" : 0.234,
    "val" : 1.678,
    "max" : 6.890
  }
]

To read the last value, a predefined function last_value is used. A function determines how the data is returned.

Parameter

Parameter Description
custom_key Addressing of the asset Definition
alias Addressing of the datastream/property Definition
function Function that is used to query data (in this case the function that returns the last value)

Response

As a response, you will always receive a JSON list of data points. The data points vary depending on the datatype. However, each element includes a timestamp.

Read data

Reading of values

curl "https://lm3api.linemetrics.com/v2/data/{{CUSTOM_KEY}}/{{ALIAS}}? ... PARAMETER ... "
  -H "Authorization: Bearer {{key}}"

Response from server

[
  {
    "average": 2.2991219917933146,
    "min": 1.6733490228652954,
    "max": 7.464624881744385,
    "count": 90,
    "sum": 206.92097926139832,
    "ts": 1461332700000
  },
  {
    "average": 0.6561659008264542,
    "min": 0.4281260073184967,
    "max": 4.751817226409912,
    "count": 90,
    "sum": 59.054931074380875,
    "ts": 1461339000000
  },
  {
    "average": 1.4405192838774787,
    "min": 1.1693300008773804,
    "max": 6.496118068695068,
    "count": 90,
    "sum": 129.64673554897308,
    "ts": 1461357900000
  },
  { "..." : "..." }
]

To query data, so-called functions are used. One function determines, how the data is returned. To query the data certain attributes (period, aggregation, etc) are needed and can vary from function to function. Therefore, you can find all different functions and the corresponding attributes in the subsection query types .

Parameter

Parameter Description
function function that should be used to query data
attributes attributes corresponding to the function that is used to query data

Response

As a response, you will always receive a JSON list of data points. The data points vary depending on the datatype. However, each element includes a timestamp.

Query types

Query of sum - function = sum

Attribute Optional Description
time_from No Query of starting time as UNIX timestamp in milliseconds
time_to No Query of end time as UNIX timestamp in milliseconds
time_zone Yes Time zone that should be used for aggregation
granularity Yes Determines the size of the batch during aggregation. Information in accordance to ISO8601

Query of Min/Max/Avg - function = average

Attribute Optional Description
time_from No Query of starting time as UNIX time stamp in milliseconds
time_to No Query of end time as UNIX time stamp in milliseconds
time_zone Yes Time zone that should be used for aggregation
granularity Yes Determines the size of the batch during aggregation. Information in accordance to ISO8601

Query of raw-data-function = raw

Attribute Optional Description
time_from No Query of starting time as UNIX time stamp in milliseconds
time_to No Query of end time as UNIX time stamp in milliseconds

Standard query = default

In order to not distinguish which function to use for each query, the function default is available. For each datatype, a standard function exists, that will be used in this case. If no function is used, the function default will automatically be used.

Attribute Optional Description
time_from No Query of starting time as UNIX time stamp in milliseconds
time_to No Query of end time as UNIX time stamp in milliseconds
time_zone Yes Time zone that should be used for aggregation
granularity Yes Determines the size of the batch during aggregation. Information in accordance to ISO8601

HTTP Status

Status Description
2*, 3* Saving process successful
403 Referred function is not supported
404 Queried stream does not exist
500 Error while querying stream. Please mail to support@linemetrics.com

Object resources

The LineMetrics asset model organizes all different kind of data in a structured format, so that links and relations between data can be found more easily from the user’s point of view. A more specific explanation can be found in the section Addressing.

Query a single resource

Query objects

curl "https://lm3api.linemetrics.com/v2/object/{{CUSTOM_KEY}}/{{ALIAS}}?last_value=true"
  -H "Authorization: Bearer {{key}}"

Response from server

{
    "object_id": "...",
    "object_type": "object",
    "model_type": "object",
    "template_id": "...",
    "parent_id": "...",
    "payload": { "..." : "..." }   
}

Using this interface, a single resource can be queried.

Parameter

Parameter Optional Description
custom_key No Addressing of the asset Definition
alias Yes Addressing of the datastream/property Definition
last_value Yes Should last value be queried(true/false)

Response

Parameter Description
object_id The distinct ID of the object
object_type Type of resource
template_id Reference to a template (resource was created as an instance of a template)
parent_id Reference to the parent-element
payload resource-specific data
data Value of the property (if the resource is of type property)
input Reference to data source (if a linkage does exist)
children_info Key/value list with object type as key and number of sub-objects as value
custom_key Custom key (if the resource is an asset and the value has been defined)
alias Alias (if the resource is a datastream/property and the value has been defined)
last_value last value of a datastream

HTTP Status

Status Description
2*, 3* Query successful
400 Parameter necessary
500 Error while processing the query. Please mail to support@linemetrics.com

Query list of children of a resource

Query resources children

curl "https://lm3api.linemetrics.com/v2/children/{{CUSTOM_KEY}}/{{ALIAS}}? ... PARAMETER ..."
  -H "Authorization: Bearer {{key}}"

Response from server

[
    {
        "object_id": "...",
        "object_type": "object",
        "model_type": "object",
        "template_id": "...",
        "parent_id": "...",
        "payload": { "..." : "..." }
    },
    { "..." : "..." }
]

Using this interface, all children of a resource can be queried.

Parameter

Parameter Optional Description
custom_key Yes Addressing of the asset Definition
alias Yes Addressing of the datastream/property Definition
limit Yes Number of objects that should be loaded
offset Yes Number of objects that should be skipped
object_type Yes Type of objects that should be loaded (string and list of types possible)
load_property_data Yes Load value - if it is a property
load_input_ref Yes Load UID of the stream, which contains the actual data of the resource

Response

List of objects

Parameter Description
object_id The distinct ID of the object
object_type Type of resource
template_id Reference to a template (resource was created as an instance of a template)
parent_id Reference to the parent-element
payload Resources of specific data
data Value of the property (if the resource is of type property)
input Reference to data source (if a linkage does exist)
children_info Key/value list with object type as key and number of sub-objects as value
custom_key Custom key (if the resource is an asset and the value has been defined)
alias Alias (if the resource is a datastream/property and the value has been defined)

HTTP Status

Status Description
2*, 3* Successful query
400 Parameter necessary
500 Error when processing the query. Please mail to support@linemetrics.com

Delete a resource

Delete a resource

curl "https://lm3api.linemetrics.com/v2/object/{{CUSTOM_KEY}}/{{ALIAS}}? ... PARAMETER ..."
  -X DELETE
  -H "Authorization: Bearer {{key}}"

Using this interface, a resource (and its children) can be deleted.

Parameter

Parameter Optional Description
custom_key No Addressing of the asset Definition
alias Ja Addressing of the datastream/characteristic Definition
recursive Yes Recursive deletion (all children will be deleted as well) starting at the selected resource

HTTP Status

Status Description
2*, 3* Successful query
400 Parameter necessary, validation failed, see error report
500 Error when processing the query. Please mail to support@linemetrics.com

Update a resource

Update a resource

curl "https://lm3api.linemetrics.com/v2/object/{{CUSTOM_KEY}}/{{ALIAS}}"
  -X POST
  -H "Authorization: Bearer {{KEY}}"
  -d "
  {
      "custom_key" : "...",
      "alias" : "...",
      "name" : "..."
  }
  "

Response from server

{
  "message" : "Update Successful"
}

Using this interface, resources can be changed. In the current version, the options are limited to basic functions.

GET-Parameter

Parameter Optional Description
custom_key No Addressing of the asset Definition
alias Yes Addressing of the datastream/characteristic Definition

POST-Parameter

Parameter Optional Description
custom_key Yes New addressing of the asset Definition
alias Yes New addressing of the datastream/characteristic Definition
name Yes Visual identifier of the resource
parent Yes Parent object under which the actual object will be added. Addressing of the parent object via objectID or customKey Definition

HTTP Status

Status Description
2*, 3* Successful query
400 Parameter necessary, validation failed, see error report
404 Resource not found
500 Error when updating resource. Please mail to support@linemetrics.com

File resources

Query file resources

Query file

curl "https://lm3api.linemetrics.com/v2/file/{{FILE_ID}}"
  -H "Authorization: Bearer {{key}}"

Response from server binary data

With this interface, a file resource can be queried.

Parameter

Parameter Optional Beschreibung
file_id No Addressing of the File

Response

In success, the binary data of the file are transmitted.

HTTP Status

Status Description
2*, 3* Successful query
400 Parameter necessary, validation failed, see error report
500 Error when processing the query. Please mail to support@linemetrics.com

QR Code Ressourcen

Query resources

Query ressource

curl "https://lm3api.linemetrics.com/v2/link/{{link_id}}"
  -H "Authorization: Bearer {{key}}"

Response from server

{
    "object_type": "...",
    "payload": { "..." : "..." }    
}

With this interface objects, measurement points, files or guidances can be queried by a link ID. The link_id (object_id) in a QR Code URL is located as a parameter.

Parameter

Parameter Optional Description
link_id No Addressing of the link

Antwort

Parameter Description
object_id The distinct ID of the object
object_type Type of resource
payload resource-specific data
children_info Key/value list with object type as key and number of sub-objects as value
custom_key Custom key (if the resource is an asset and the value has been defined)

HTTP Status

Status Description
2*, 3* Successful query
400 Parameter necessary, validation failed, see error report
404 Link not found
404 Resource not found
403 No authorization
406 Empty link
500 Error when processing the query. Please mail to support@linemetrics.com

Update link

    curl "https://lm3api.linemetrics.com/v2/link/{{link_id}}"
  -X POST
  -H "Authorization: Bearer {{KEY}}"
  -d " { "object_id" : "..." "type": "..."} "

Response from server

{
  "message" : "Update Successful"
}

You can use this interface to fill an empty link object with data. The link_id (object_id) in a QR Code URL is located as a parameter.

GET-Parameter

Parameter Optional Description
link_id Nein ID of the link

POST-Parameter

Parameter Optional Description
object_id No The ID of the object to be linked
type No Type of the object to be linked (object, attribute, guidance, document)

HTTP Status

Status Description
2*, 3* Successful query
400 Parameter necessary, validation failed, see error report
404 Link not found
406 The link is not empty
500 Error when updating resource. Please mail to support@linemetrics.com

Unlink

  curl "https://lm3api.linemetrics.com/v2/link/{{link_id}}"
    -X Delete
    -H "Authorization: Bearer {{KEY}}"

Response from server

{
  "message" : "Deleted Successful"
}

With this interface links can be detached again.

Parameter

Parameter Optional Description
link_id Nein Adressierung der Verknüpfung /

HTTP Status

Status Description
2*, 3* Successful detached
400 Parameter necessary, validation failed, see error report
404 Link not found
406 The link is empty
500 Error when updating resource. Please mail to support@linemetrics.com

Templates

Query existing templates

Query templates

curl "https://lm3api.linemetrics.com/v2/templates"
  -H "Authorization: Bearer {{KEY}}"

Response from server

[
  {
    "uid": "...",
    "name": "..."
  },
  { "..." : "..." }
]

Using this interface, all existing and available templates can be queried.

Response

List of templates

Parameter Description
uid Distinct ID of the template
name Visual identifier of the template

Query required fields

Query required fields

curl "https://lm3api.linemetrics.com/v2/template/{{TEMPLATE_UID}}/required-fields"
  -H "Authorization: Bearer {{KEY}}"

Response from server

[
  {
    "uid": "...",
    "data_type": "...",
    "alias": "..."
  },
  { "..." : "..." }
]

Using this interface, all required fields of the transmitted template can be queried

Parameter

Parameter Optional Description
template_uid No Distinct ID of the template

Response

List of templates

Parameter Description
uid Distinct ID of the mandatory field
data_type Datatype to write data on a datastream/characteristic Definition
alias Addressing of the datastream/characteristic Definition

HTTP Status

Status Description
2*, 3* Successfull query
400 Parameter necessary, validation failed, see error report
404 Template not found

Create asset using a template

Create asset using a template

curl "https://lm3api.linemetrics.com/v2/template/{{TEMPLATE_UID}}"
  -X POST
  -H "Authorization: Bearer {{KEY}}"
  -d "
  {
      "{{ALIAS}}" : {
        "val" : 1.678
      }
  }
  "

Response from server

  {
    "uid": "..."
  }

Using this interface, a new asset can be created out of an existing template

GET-Parameter

Parameter Optional Description
template_uid No Distinct ID of the template

POST-Parameter

The POST-Parameter go by the mandatory fields of the template. In case no mandatory fields are defined in the template, you do not have to define anything here. Otherwise, the alias or the UID will be used as key and the value of the mandatory field will be used as the value, dependent on the datatype.

Response

UID of the just created asset.

Parameter Description
uid Distinct ID of the asset

HTTP Status

Status Description
2*, 3* Successful query
400 Parameter necessary, validation failed, see error report
500 Error when creating the asset. Please mail to support@linemetrics.com

Article

Query single article

Query article

curl "https://lm3api.linemetrics.com/erp/article/{{ARTICLE_KEY}}/"
  -H "Authorization: Bearer {{KEY}}"

Response from server

{
  "object_id": "...",
  "object_type": "article",
  "model_type": "erp",
  "payload": {
    "images": {
      "file_id": "...",
      "thumbnail_id": "..."
    },
    "title": "...",
    "type": "article",
    "description":  "...",
    "short_description": "...",
    "article_type": "...",
    "article_number": "...",
    "tariff_number": "...",
    "article_group": "...",
    "article_supplier": "...",
    "website": "...",
    "price": "...",
    "currency": {"": ""},
    "payable": true/false,
    "shippable": true/false,
    "documents": [
             {
            "file_id": "...",
            "title": "...",
            "url": "...",
            "document_format": "..."
              }
         ],
    "guidance": [
              {
            "file_id": "...",
            "title": "...",
            "url": "...",
            "document_format": "guidance"
              }
        ]
  }
}

Using this interface, existing articles can be queried by using articleID or EAN-number.

Parameter

Parameter Optional Description
article_key No ArticleID or EAN-number

Response

Parameter Description
object_id Distinct ID of article
object_type fix “article”
model_type fix “erp”
payload resource-specific data
images Images that are added to the article
titel title of the article
description description of the article
short_description short form of the description
article_type Distinction whether the article is a product, a service or other
article_number article number
tariff_number customs tarif number
article_group Article group, the article belongs to
article_supplier Supplier from which the article is bought
website Website of the supplier
payable if the article is payable
shippable whether an article has to be shipped or not
documents list of documents that are added to the article guidance

HTTP Status

Status Description
200 Process successful
500 article not found

Query single guidance

Query guidance

curl "https://lm3api.linemetrics.com/erp/guidance/{{GUIDANCE}}/"
  -H "Authorization: Bearer {{KEY}}"

Response from server

{
  "object_id": "...",
  "object_type": "guidance",
  "model_type": "erp",
  "payload": {
    "title": "...",
    "type": "guidance",
    "images": {
      "file_id": "...",
      "thumbnail_id": "..."
    },
    "duration": "...",
    "difficulty": "...",
    "tools": ["...", "..." ],
    "skills": ["...", "..." ],
    "steps": [
        {
          "id": "...",
          "title": "...",
          "order": "...",
          "template": "...",
          "content": "...",
          "images": [{
              "image": "...",
              "smallImage": "...",
              "bigImage": "..."
            },]
        },
      ]
}

Using this interface, guidance can be queried by using GuidanceID.

Parameter

Parameter Optional Description
guidance No GuidanceID

Response

Parameter Description
object_id Distinct ID of the guidance
object_type fix “guidance”
model_type fix “erp”
payload Resource-specific data
images main image of the guidance
titel titel of the guidance
duration time required for using the guidance
difficulty difficulty of the guidance
tools required tools for the guidance
skills required skills for the guidance
steps list of steps to successfully complete the installation steps[id]
steps[title] titel of the step
steps[order] order of the steps
steps[template] type of step text(only text), text_picture(test with picture), text_gallery(text with up to 3 pictures)
steps[content] content of the step
steps[images] list of pictures that are shown at the step

HTTP Status

Status Description
200 Process successful
500 Guidance not found