LineMetrics API (v1)

Willkommen bei der LineMetrics REST API Dokumentation. Die LineMetrics API soll es Ihnen ermöglichen, auf die Basisfunktionalität der LineMetrics Cloud zuzugreifen. Dazu gehört unter anderem das Abfragen von bestehenden Streams und das Speichern von Daten in einem der API zugewiesenen Eingang.

Beispielcode stellen wir aktuell zum Testen nur für Unix-Kommandozeile (Shell) zur Verfügung. Es ist geplant, den Beispielcode für andere Programmiersprachen sukzessive auszubauen. Wir freuen uns hier gerne über Ihre Mithilfe.

Die API befindet sich aktuell in der Version 1, wobei sich diese Version gerade im Aufbau befindet. Bestehende Endpunkten “sollten” sich nicht mehr verändern, es werden aber laufend neue Endpunkte hinzukommen. Die Versionierung soll eine nahtlose Adaptierung von bestehenden Endpunkten ermöglichen, ohne die Abwärtskompatibilität zu beeinflussen.

Authentifizierung

OAuth2

Authentifizieren mittels 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

Antwort vom Server

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

Die aktuelle Version der REST API Dokumentation unterstützt ausschließlich eine Authentifizierung mittels Client-Credentials über das OAuth2 Protokoll. Dabei muss über einen REST Aufruf und der Parameter Client ID und Client Secret ein Session Token erzeugt werden. Mit diesem Session Token können dann Abfragen auf die anderen Ressourcen (Daten/Objekt Ressourcen) durchgeführt werden.

Parameter

Parameter	Beschreibung
client_id	ID die den Zugang eindeutig identifiziert
client_secret	Client Secret, welche den Zugriff mittels Client ID authorisiert und es erlaubt einen neuen Session Token zu erzeugen
grant_type	Art der OAuth-Authentifizierung. Aktuell wird nur die client_credentials Authentifizierung unterstützt. Dh ein Zugriff über Session Token, welcher mittels client_id und client_secret erzeugt wird.

Antwort

Parameter	Beschreibung
access_token	Session Token der für alle weiteren Abfragen auf API Ressourcen verwendet und per Header übergeben wird.
token_type	Definiert die Art des Session Tokens und wird beim Authentifizieren als Prefix im Header mitangegeben.
expires_in	Gültigkeitsdauer des Tokens in Sekunden

Daten Typen

Daten Typen sind ein essenzieller Bestandteil im Umgang mit Daten in der LineMetrics Cloud bzw. im Umgang mit der Rest API, weil durch Daten Typen festgelegt werden kann, wie die eigentlichen Daten aussehen bzw. welche Ausprägungen ein einzelner Datenpunkt besitzt.

Daten Typen erhält man einerseits bei der Abfrage der für den API Endpunkt verfügbaren Eingänge (Inputs) bzw. auch wenn konkrete Messpunkte eines Objekts abgefragt werden.

Double

{
  "val" : 123.0
}

Einfacher Datentyp der nur einen primitiven double Datentyp kapselt.

Parameter	Prim. Datentyp	Beschreibung
val	Double	Wert

DoubleAverage

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

Ein Datentyp der neben dem Durchschnittswert auch die Grenzwerte (Min/Max) eines Datenpunkts liefert.

Parameter	Prim. Datentyp	Beschreibung
val	Double	Durchschnittswert
min	Double	Minimum Wert
max	Double	Maximum Wert

Bool

{
  "val" : 0
}

Einfacher Datentyp der nur einen primitiven bool Datentyp kapselt.

Parameter	Prim. Datentyp	Beschreibung
val	Boolean	Booleanwert 0 oder 1

GeoCoord

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

Ein Datentyp der Geokoordinaten in Form eines Longitude und Latitude Wertes kapselt.

Parameter	Prim. Datentyp	Beschreibung
lat	Double	Latitude GPS Wert (Geographische Breite)
long	Double	Longitude GPS Wert (Längengrad)

String

{
  "val" : "Mein Text"
}

Einfacher Datentyp der nur einen primitiven String Datentyp kapselt.

Parameter	Prim. Datentyp	Beschreibung
val	String	Text

Daten Ressourcen

Liste mit API Eingängen

Abfragen der verfügbaren Eingänge des API Endpunkts

curl "https://lm3api.linemetrics.com/v1/data/inputs"
  -H "Authorization: Bearer {{key}}"

Antwort vom Server

[
  {
    "input_title": "Temperatur",
    "input_id": "...",
    "data_type": "DoubleAverage"
  },
  {
    "input_title": "Luftfeuchtigkeit",
    "input_id": "...",
    "data_type": "DoubleAverage"
  }
]

Für jeden API Zugang können auch API Eingänge konfiguriert werden. Diese Eingänge können verwendet werden um Daten an die LineMetrics Cloud zu schicken. Über die /v1/data/inputs Schnittstelle können alle verfügbaren API Eingänge abgerufen werden.

Antwort

Parameter	Beschreibung
input_title	Name des Eingangs
input_id	Eindeutige Kennzeichnung des Eingangs
data_type	Datentyp des Eingangs. Dieser definiert auch das Schema der Daten, welches beim Speichern berücksichtigt werden muss.

HTTP Status

Status	Beschreibung
2*, 3*	Aufruf erfolgreich
409	Es gibt keine Eingänge auf die geschrieben werden kann

Daten schreiben

Speichern von Werten

curl "https://lm3api.linemetrics.com/v1/data/write"
  -H "Authorization: Bearer {{key}}"
  -d "
  [
    {
      "input_id" : "...",
      "data_type" : "DoubleAverage",
      "data_payload" : {
        "min" : 0.234,
        "val" : 1.678, 
        "max" : 6.890
      }
    }
  ]
  "

Antwort vom Server

[
  {
    "input_id": "34f899b4aa60450b89661a07403bd3cf",
    "response": "Success"
  }
]

Zum Speichern von neuen Werten muss eine Liste von Elementen übergeben werden, die jeweils einen zu speichernden Messpunkt repräsentieren. Sollten Sie nur einen einzelnen Wert speichern wollen, übergeben Sie bitte eine Liste mit nur einem Element.

Sollte der Speichervorgang fehl schlagen, überprüfen Sie bitte den HTTP Status bzw. den Speicherstatus.

Parameter

Parameter	Beschreibung
input_id	ID die den Eingang auf den geschrieben wird, eindeutig identifiert. Die verfügbaren Inputs können mit der API Ressource Liste mit API Eingängen abgefragt werden.
data_type	Definiert den Datentyp des Messpunkts der gespeichert werden soll. Dieser muss mit der Einstellung des Eingangs übereinstimmen.
data_payload	Die eigentlichen Daten des Messpunkts. Richtet sich nach dem Datentyp (siehe Abschnitt “Daten Typen”)

Antwort

Parameter	Beschreibung
input_id	ID die den Eingang auf den geschrieben wurde, eindeutig identifiert.
response	Status die definiert, ob ein Wert gespeichert wurde.

Speicherstatus

Status	Beschreibung
success	Speichervorgang erfolgreich
Unknown	Datentyp entspricht nicht der Einstellung oder Input wurde nicht gefunden

HTTP Status

Status	Beschreibung
2*, 3*	Speichervorgang erfolgreich
400	Falsche JSON Struktur / Formatierung / Daten fehlen
409	Es gibt keine Eingänge auf die geschrieben werden kann

Daten lesen

Lesen von Werten

curl "https://lm3api.linemetrics.com/v1/data/read"
  -H "Authorization: Bearer {{key}}"
  -d "
    {
      "function" : "avg",
      "attributes" : {
        "object_id" : "{{OBJECT_ID}}",
        "time_from" : 1461327519000,
        "time_to" : 1461427519000,
        "time_zone" : "Europe/Vienna",
        "granularity" : "PT15M"
      }
    }
  "

Antwort vom 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
  },
  { "..." : "..." }
]

Für das Abfragen von Daten werden sogenannte Funktionen verwendet. Eine Funktion definiert hierbei, wie die Daten zurückgegeben werden sollen. Für die Abfrage werden verschiedenste Attribute benötigt (Zeitraum der Abfrage, Aggregation, …) die aber immer Funktionsspezifisch sind. Aus diesem Grund finden Sie im Unterabschnitt Abfragearten die unterschiedlichen Funktionen und die benötigten Attribute.

Parameter

Parameter	Beschreibung
function	Die Funktion die verwendet werden soll um Daten abzufragen
attributes	Die Funktions spezifischen Attribute die für die Abfrage benötigt werden

Antwort

Als Antwort erhalten Sie immer eine JSON Liste mit Datenpunkten. Die Datenpunkte varieren hier nach dem Datentyp. Ein jedes Element beinhaltet aber immer einen Zeitstempel.

Abfragearten

Abfrage von Summen - Function = sum

Attribut	Optional	Beschreibung
time_from	Nein	Abfrage Startzeit als Unixzeitstempel in Millisekunden
time_to	Nein	Abfrage Endzeit als Unixzeitstempel in Millisekunden
object_id	Nein	Eindeutige Kennzeichnung des Streams, der abgefragt werden soll (z.B. input_id). Die verfügbaren Streams können über die Objekt Ressource abgefragt werden.
time_zone	Ja	Zeitzone die für die Aggregation verwendet werden soll
granularity	Ja	Definiert die Größe eines Batches bei der Aggregation. Angabe nach ISO8601

Abfrage von Min/Max/Avg - Function = avg

Attribut	Optional	Beschreibung
time_from	Nein	Abfrage Startzeit als Unixzeitstempel in Millisekunden
time_to	Nein	Abfrage Endzeit als Unixzeitstempel in Millisekunden
object_id	Nein	Eindeutige Kennzeichnung des Streams, der abgefragt werden soll (z.B. input_id). Die verfügbaren Streams können über die Objekt Ressource abgefragt werden.
time_zone	Ja	Zeitzone die für die Aggregation verwendet werden soll
granularity	Ja	Definiert die Größe eines Batches bei der Aggregation. Angabe nach ISO8601

Abfrage von Rohdaten - Function = raw

Attribut	Optional	Beschreibung
time_from	Nein	Abfrage Startzeit als Unixzeitstempel in Millisekunden
time_to	Nein	Abfrage Endzeit als Unixzeitstempel in Millisekunden
object_id	Nein	Eindeutige Kennzeichnung des Streams, der abgefragt werden soll (z.B. input_id). Die verfügbaren Streams können über die Objekt Ressource abgefragt werden.

Standardabfrage = default

Um nicht bei jeder Abfrage unterscheiden zu müssen, mit welcher Funktion abgefragt werden soll, gibt es die default Funktion. Für jeden Datentyp ist eine Standard Funktion hinterlegt, die in diesem Fall dann verwendet wird.

Attribut	Optional	Beschreibung
time_from	Nein	Abfrage Startzeit als Unixzeitstempel in Millisekunden
time_to	Nein	Abfrage Endzeit als Unixzeitstempel in Millisekunden
object_id	Nein	Eindeutige Kennzeichnung des Streams, der abgefragt werden soll (z.B. input_id). Die verfügbaren Streams können über die Objekt Ressource abgefragt werden.
time_zone	Ja	Zeitzone die für die Aggregation verwendet werden soll
granularity	Ja	Definiert die Größe eines Batches bei der Aggregation. Angabe nach ISO8601

HTTP Status

Status	Beschreibung
2*, 3*	Speichervorgang erfolgreich
403	Angegebene Funktion wird nicht unterstützt
404	Stream der abgefragt wird, existiert nicht
500	Fehler beim Abfragen der Stream Daten

Objekt Ressourcen

Mit dem LineMetrics Objekt Modell werden verschiedenste Daten in eine strukturierte Form gebracht, sodass aus Benutzersicht Zusammenhänge und Relationen zwischen diesen Daten besser hergestellt werden können.

So gibt es beispielweise ein spezielles Objekt Modell, welches nur die verfügbaren Datenquellen eines Accounts darstellt, oder ein Objekt Modell, welches Messpunkte (dh Daten die vom Kunden aufgezeichnet werden) so strukturiert, dass es einem Kunden möglich ist, alle Messpunkte einer geografischen Einheit (z.B. Filiale) zusammenzufassen.

In einem Objektmodell werden aber nicht nur Messpunkte oder Devices abgelegt. Es werden hier auch Eigenschaften von Objekten abgelegt (zB Mitarbeiteranzahl, Raumgröße, …), die es später ermöglichen, Objekt übergreifende Auswertungen und Datenbereinigung durchzuführen (Benchmarking des Energieverbrauchs pro Quadratmeter der einzelnen Filialen).

Einzelnes Objekt abfragen

Objekt abfragen

curl "https://lm3api.linemetrics.com/v1/object/read"
  -H "Authorization: Bearer {{key}}"
  -d "
  {
      "object_id" : "...",
  }
  "

Antwort vom Server

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

Mit dieser Schnittstelle kann ein einzelnen Objekt anhand seiner eindeutigen ID abgefragt werden.

Parameter

Parameter	Beschreibung
object_id	Die eindeutige ID des Objekts

Antwort

Parameter	Beschreibung
object_id	Die eindeutige ID des Objekts
object_type	Typ des Objekts
model_type	Model Typ (siehe Einleitungstext Objekt Ressourcen)
template_id	Referenz auf ein Template Objekt (Objekt wurde als Instanz eines Templates angelegt)
parent_id	Referenz auf das Mutterelement
payload	Objekt Typ spezifische Daten
data	Wert der Eigenschaft (sofern das Objekt vom Typ “property” ist
input	Referenz auf Datenquelle (sofern eine Verknüpfung existiert)
children_info	Key/Value Liste mit Objekt Typ als Schlüssel und Anzahl der Unterobjekte als Wert

HTTP Status

Status	Beschreibung
2*, 3*	Abfrage erfolgreich
400	Parameter erforderlich
500	Fehler beim Verarbeiten der Abfrage

Liste von Kinder Objekte abfragen

Kinder Objekte abfragen

curl "https://lm3api.linemetrics.com/v1/object/children"
  -H "Authorization: Bearer {{key}}"
  -d "
  {
      "object_id" : "...",
      "limit" : 100,
      "offset" : 0
  }
  "

Antwort vom Server

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

Mit dieser Schnittstelle ist es möglich, alle Kinder Objekte eines Objekts abzufragen.

Parameter

Parameter	Optional	Beschreibung
object_id	Ja	Die eindeutige ID des Mutter Objekts
model_type	Ja	Objekt Modell das abgefragt werden soll
limit	Ja	Anzahl der Objekte die geladen werden sollen
offset	Ja	Anzahl der Objekte die übersprungen werden sollen
object_type	Ja	Objekt Typen die geladen werden sollen (String und Liste von Typen möglich)

Antwort

Liste von Objekten

Parameter	Beschreibung
object_id	Die eindeutige ID des Objekts
object_type	Typ des Objekts
model_type	Model Typ (siehe Einleitungstext Objekt Ressourcen)
template_id	Referenz auf ein Template Objekt (Objekt wurde als Instanz eines Templates angelegt)
parent_id	Referenz auf das Mutterelement
payload	Objekt Typ spezifische Daten

HTTP Status

Status	Beschreibung
2*, 3*	Abfrage erfolgreich
400	Parameter erforderlich