Zum Inhalt springen
DE

API der EOS IoT-Plattform

REST-API für den Zugriff auf die IoT-Gerätedaten der EOS-Plattform. Diese Dokumentation führt Sie durch die Nutzung der API, um Gerätedaten in Ihre Anwendungen zu integrieren.

📥 Laden Sie die OpenAPI-Spezifikation herunter und geben Sie sie Ihrem KI-Agenten, damit er den vollständigen Kontext der API erhält.

eos-openapi.json herunterladen

Hinweis: Dies ist ein neues Produkt (Version 1.0.0). Wir freuen uns über jedes Feedback, das uns hilft, die API zu verbessern. Teilen Sie uns Ihre Vorschläge mit oder melden Sie Probleme, auf die Sie stoßen.

Authentifizierung

Alle Requests müssen den Header x-api-key mit dem bei der Registrierung bereitgestellten API-Key enthalten.

Beispiel:

curl -H "x-api-key: YOUR_API_KEY" https://p2uyaymt8c.execute-api.eu-south-1.amazonaws.com/v1/integration/devices

Sicherheit:

  • ⚠️ Geben Sie Ihren API-Key niemals weiter
  • ⚠️ Legen Sie ihn nicht im Quellcode ab
  • ✅ Speichern Sie ihn in Umgebungsvariablen

Rate Limiting

Die API ist ratenbegrenzt, um den Dienst stabil zu halten. Die konkreten Limits hängen von Ihrem Nutzungsplan ab:

Standardplan:

  • Rate: 0,5 Requests pro Sekunde
  • Burst: 5 gleichzeitige Requests
  • Kontingent: 100.000 Requests pro Monat

Individuelle Pläne: Weitere Pläne mit anderen Limits sind verfügbar. Wenden Sie sich für mehr Informationen an den Support.

⚠️ Wichtig: Achten Sie darauf, Ihr gesamtes Kontingent nicht schon in den ersten drei Tagen des Monats aufzubrauchen. Planen Sie die Nutzung der API so, dass die Requests gleichmäßig über den gesamten Abrechnungszeitraum verteilt sind und das Kontingent nicht vorzeitig erschöpft ist.

Mehrere Messwerte

Manche Geräte können mehrere Sensoren desselben Typs haben. Ein Gerät kann zum Beispiel haben:

  • Zwei Temperatursensoren (einen internen und einen externen)

In diesen Fällen:

  • Das Feld measure ist identisch (z. B. "temperature")
  • Das Feld sensor_type unterscheidet sich (z. B. "in100-q1-r-rc0i" vs. "sht40-ad1b-r2")

Verwenden Sie bei Bedarf den Parameter sensorType, um einen bestimmten Sensor zu filtern.

Datumsformat

Alle Datumsangaben müssen im Format ISO 8601 mit Zeitzone UTC vorliegen:

  • Format: YYYY-MM-DDTHH:mm:ssZ
  • Beispiel: 2026-02-04T15:30:00Z

Granularität der historischen Daten

Der Endpoint /devices/{deviceId}/history unterstützt mehrere Granularitäten:

  • raw: Rohdaten ohne Aggregation
  • 15m: Alle 15 Minuten aggregierte Daten (Mittelwert, Min, Max)
  • 1h: Stündlich aggregierte Daten (Mittelwert, Min, Max)
  • 1d: Täglich aggregierte Daten (Mittelwert, Min, Max)

Paginierung

Der Endpoint /devices/{deviceId}/history unterstützt Paginierung:

  • limit: Maximale Anzahl an Ergebnissen (Standard: 100, max.: 100)
  • offset: Anzahl der zu überspringenden Ergebnisse (Standard: 0)
  • Die Antwort enthält die Paginierungsinformationen im Feld pagination

Datenverfügbarkeit

Die Verfügbarkeit historischer Daten hängt von der Granularität und vom Installationsdatum des Sensors ab:

  • Beginn der Datenverfügbarkeit: Daten sind für jedes Gerät ab dem Installationsdatum des Sensors verfügbar
  • Rohdaten: 30 Tage ab dem aktuellen Datum verfügbar
  • Hochfrequente CSV-Datendateien: 30 Tage ab dem aktuellen Datum verfügbar (gleiche Aufbewahrung wie Rohdaten)

Hinweis: Diese Funktion ist nur verfügbar, wenn Sie hochfrequente Geräte haben (z. B. Motorsensoren). Hat Ihr Tenant/Standort keine hochfrequenten Geräte, gibt die API eine Fehlermeldung zurück.

  • 15-Minuten-Aggregate (15m): 90 Tage ab dem aktuellen Datum verfügbar
  • Stündliche Aggregate (1h): 2 Jahre ab dem aktuellen Datum verfügbar
  • Tägliche Aggregate (1d): Dauerhaft verfügbar (kein Ablauf)

Empfehlungen:

  • Verwenden Sie raw für detaillierte Analysen der jüngsten Daten (letzte 30 Tage)
  • Verwenden Sie die hochfrequenten CSV-Dateien für Massen-Downloads aktueller Daten (letzte 30 Tage)
  • Verwenden Sie 15m für mittelfristige Trends (bis zu 90 Tage)
  • Verwenden Sie 1h für langfristige Analysen (bis zu 2 Jahre)
  • Verwenden Sie 1d für historische Analysen über 2 Jahre hinaus

Support

Für Hilfe oder Fragen wenden Sie sich an den technischen Support.

HTTP-Statuscodes

  • 200 OK: Request erfolgreich abgeschlossen
  • 400 Bad Request: Fehlerhafter Request oder fehlende Parameter
  • 401 Unauthorized: API-Key fehlt oder ist ungültig
  • 403 Forbidden: Zugriff verweigert
  • 404 Not Found: Ressource nicht gefunden
  • 500 Internal Server Error: Interner Serverfehler

Geräte

Operationen zur Abfrage der verfügbaren IoT-Geräte.

Mit diesen Endpoints können Sie:

  • Die Liste der Geräte abrufen
  • Die für jedes Gerät verfügbaren Messwerte abfragen

Geräte auflisten

Gibt die Liste der Geräte zurück, die für Ihren API-Key verfügbar sind.

Verhalten:

  • Ohne Parameter: gibt alle verfügbaren Geräte zurück
  • Mit includeMeasures=true: schließt die für jedes Gerät verfügbaren Messwerte ein

Performance:

  • Ohne includeMeasures: schnelle Abfrage, ideal für lange Listen
  • Mit includeMeasures=true: langsamere Abfrage, nur bei Bedarf verwenden

Anwendungsbeispiele:

  • Einfache Liste: GET /devices
  • Mit Messwerten: GET /devices?includeMeasures=true

Authorization: ApiKeyAuth

Query-Parameter

includeMeasures boolean · Standard: false · Beispiel: includeMeasures=true

Wenn true, werden die für jedes Gerät verfügbaren Messwerte im Feld available_measures mitgeliefert.

Wann verwenden:

  • Wenn Sie vor den Datenabfragen wissen müssen, welche Messwerte verfügbar sind
  • Wenn Sie den Nutzern die verfügbaren Optionen anzeigen möchten

Wann NICHT verwenden:

  • Wenn Sie nur die Geräteliste benötigen (schneller)
  • Wenn Sie bereits Informationen über die verfügbaren Messwerte haben

Antworten

  • 200 · Geräteliste erfolgreich zurückgegeben
  • 400 · Ungültiger Request. Häufige Ursachen: fehlende oder fehlerhafte Parameter, Werte außerhalb des zulässigen Bereichs, ungültiges Datumsformat, leeres oder zu großes Array
  • 401 · Nicht autorisiert, Authentifizierung fehlgeschlagen. Ursachen: API-Key fehlt im Header x-api-key, API-Key ungültig oder abgelaufen, API-Key keinem gültigen Usage Plan zugeordnet
  • 403 · Zugriff verweigert, unzureichende Berechtigungen
  • 500 · Interner Serverfehler. Wiederholen Sie den Request nach einigen Sekunden; besteht das Problem weiterhin, wenden Sie sich an den Support und geben Sie die requestId an, falls sie in Ihren Logs vorhanden ist

get /devices

Daten

Operationen für den Zugriff auf Gerätedaten.

Mit diesen Endpoints können Sie:

  • Den letzten verfügbaren Wert eines Geräts abrufen
  • Die letzten Werte mehrerer Geräte in einem einzigen Aufruf abrufen
  • Historische Daten in verschiedenen Granularitäten abfragen
  • Nach Messwerttyp und Sensor filtern

Letzter Wert des Geräts

Gibt den letzten verfügbaren Wert eines bestimmten Geräts zurück.

Verhalten je nach Parametern:

  • Ohne Parameter (GET /devices/{deviceId}/last): gibt alle Messwerte des letzten verfügbaren Zeitstempels zurück. Format: Objekt mit device_id, timestamp und einem Array data. Nützlich, wenn Sie alle gleichzeitig erfassten Messwerte sehen möchten
  • Mit measure (GET /devices/{deviceId}/last?measure=temperature): gibt nur diesen Messwert zurück. Teilen sich mehrere Sensoren denselben measure, werden alle zurückgegeben. Format: einzelnes Objekt oder Array (bei mehreren Sensoren)
  • Mit measure und sensorType (GET /devices/{deviceId}/last?measure=temperature&sensorType=in100-q1-r-rc0i): gibt nur diesen spezifischen Sensor zurück. Format: einzelnes Objekt

Anwendungsbeispiele:

  • Alle Messwerte: GET /devices/aa:bb:cc:dd:ee:ff/last
  • Nur Temperatur: GET /devices/aa:bb:cc:dd:ee:ff/last?measure=temperature
  • Spezifischer Sensor: GET /devices/aa:bb:cc:dd:ee:ff/last?measure=temperature&sensorType=in100-q1-r-rc0i

Authorization: ApiKeyAuth

Pfad-Parameter

deviceId required string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ · Beispiel: aa:bb:cc:dd:ee:ff

Geräte-ID (MAC-Adresse im Format XX:XX:XX:XX:XX:XX). Trennzeichen: Doppelpunkt (:). Groß-/Kleinschreibung wird nicht unterschieden.

Query-Parameter

  • measure string · Beispiel: measure=temperature. Filtert nach Messwerttyp. Zulässige Werte: jeder von den Sensoren zurückgegebene Messwerttyp (z. B. temperature, humidity, pressure, co2, battery_percentage, battery_voltage, rssi, a_current, b_current, c_current, total_current, a_voltage, b_voltage, c_voltage, a_act_power, b_act_power, c_act_power, total_act_power usw.) oder "all", um alle Messwerte zurückzugeben. Der Wert muss exakt dem von den Sensoren zurückgegebenen Feld measure entsprechen (Groß-/Kleinschreibung wird unterschieden)
  • sensorType string · Beispiel: sensorType=in100-q1-r-rc0i. Filtert nach Sensortyp. Beispiele: in100-q1-r-rc0i (interner Temperatursensor), sht40-ad1b-r2 (externer Temperatursensor), dht22 (Feuchte-/Temperatursensor). Hinweis: muss zusammen mit measure verwendet werden, um wirksam zu sein

Antworten

  • 200 · Letzte(r) Wert(e) erfolgreich zurückgegeben
  • 400 · Ungültiger Request
  • 401 · Nicht autorisiert, Authentifizierung fehlgeschlagen
  • 403 · Zugriff verweigert, unzureichende Berechtigungen
  • 404 · Ressource nicht gefunden. Ursachen: nicht existierende Geräte-ID, Gerät mit Ihrem API-Key nicht zugänglich, keine Daten für das angeforderte Gerät verfügbar. Hinweis: Existiert das Gerät, hat aber keine Daten, erhalten Sie trotzdem einen 404
  • 500 · Interner Serverfehler

get /devices/{deviceId}/last

Beispielantwort (mit measure und sensorType, einzelnes Objekt):

{
  "timestamp": "2026-02-04T15:30:00Z",
  "device_id": "aa:bb:cc:dd:ee:ff",
  "sensor_type": "in100-q1-r-rc0i",
  "measure": "temperature",
  "unit": "C",
  "value": 22.5
}

Letzte Werte mehrerer Geräte

Gibt die letzten Werte mehrerer Geräte in einem einzigen Aufruf zurück.

Vorteile:

  • Reduziert die Anzahl der nötigen HTTP-Aufrufe
  • Effizienter beim Lesen von Daten vieler Geräte
  • Behält dieselbe Filterlogik wie /devices/{deviceId}/last bei

Einschränkungen:

  • Maximal 100 Geräte pro Request
  • Längerer Timeout bei großen Listen

Verhalten:

  • Ohne measure: gibt alle Messwerte für jedes Gerät zurück
  • Mit measure: gibt nur diesen Messwert für jedes Gerät zurück
  • Mit measure und sensorType: gibt nur diesen Sensor für jedes Gerät zurück

Anwendungsbeispiele:

  • Alle Geräte, alle Messwerte: POST /devices/last/bulk mit {"deviceIds": [...]}
  • Alle Geräte, nur Temperatur: POST /devices/last/bulk mit {"deviceIds": [...], "measure": "temperature"}
  • Spezifischer Sensor: POST /devices/last/bulk mit {"deviceIds": [...], "measure": "temperature", "sensorType": "in100-q1-r-rc0i"}

Authorization: ApiKeyAuth

Request-Body-Schema: application/json

  • deviceIds required Array of strings [ 1 .. 100 ] items · Liste der abzufragenden Geräte-IDs. Minimum: 1 Gerät. Maximum: 100 Geräte. Format: Array von Strings (MAC-Adresse)
  • measure string · Filtert nach Messwerttyp (optional). Wenn weggelassen, werden alle Messwerte für jedes Gerät zurückgegeben
  • sensorType string · Filtert nach Sensortyp (optional). Muss zusammen mit measure verwendet werden, um wirksam zu sein

Antworten

  • 200 · Letzte Werte erfolgreich zurückgegeben
  • 400 · Ungültiger Request
  • 401 · Nicht autorisiert, Authentifizierung fehlgeschlagen
  • 403 · Zugriff verweigert, unzureichende Berechtigungen
  • 500 · Interner Serverfehler

post /devices/last/bulk

Beispiel-Request:

{
  "deviceIds": ["aa:bb:cc:dd:ee:ff", "11:22:33:44:55:66", "ff:ee:dd:cc:bb:aa"]
}

Beispielantwort:

{
  "results": [{}, {}],
  "count": 2,
  "requested": 2
}

Historische Daten des Geräts

Gibt die historischen Daten eines Geräts innerhalb eines angegebenen Zeitraums zurück.

Verfügbare Granularitäten:

  • raw (Standard): Rohdaten ohne Aggregation. Jede Zeile ist ein einzelner Messwert. Maximale zeitliche Präzision, mehr zurückgegebene Daten
  • 15m: Alle 15 Minuten aggregierte Daten. Jede Zeile enthält Mittelwert, Minimum und Maximum. Reduziert das Datenvolumen erheblich
  • 1h: Stündlich aggregierte Daten. Jede Zeile enthält Mittelwert, Minimum und Maximum. Noch kompakter
  • 1d: Täglich aggregierte Daten. Jede Zeile enthält Mittelwert, Minimum und Maximum des Tages. Minimales Datenvolumen

Paginierung:

  • Verwenden Sie limit, um die Anzahl der Ergebnisse zu steuern (max. 100)
  • Verwenden Sie offset, um zwischen den Seiten zu wechseln
  • Die Antwort enthält pagination.hasMore, das angibt, ob weitere Daten vorhanden sind

Filter:

  • measure: Filtert nach Messwerttyp
  • sensorType: Filtert nach Sensortyp (muss mit measure verwendet werden)

Anwendungsbeispiele:

  • Vollständige Historie: GET /devices/{id}/history?startDate=...&endDate=...
  • Nur Temperatur: GET /devices/{id}/history?startDate=...&endDate=...&measure=temperature
  • Spezifischer Sensor: GET /devices/{id}/history?startDate=...&endDate=...&measure=temperature&sensorType=in100-q1-r-rc0i
  • Aggregierte Daten: GET /devices/{id}/history?startDate=...&endDate=...&granularity=1d

Authorization: ApiKeyAuth

Pfad-Parameter

deviceId required string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ · Beispiel: aa:bb:cc:dd:ee:ff. Geräte-ID (MAC-Adresse)

Query-Parameter

  • startDate required string <date-time> · Beispiel: startDate=2026-02-04T00:00:00Z. Startdatum/-zeit des Zeitraums (ISO 8601, UTC)
  • endDate required string <date-time> · Beispiel: endDate=2026-02-04T23:59:59Z. Enddatum/-zeit des Zeitraums (ISO 8601, UTC). Hinweis: muss nach startDate liegen
  • granularity string · Standard: "raw" · Enum: "raw" "15m" "1h" "1d". Granularität der zurückgegebenen Daten
  • measure string · Beispiel: measure=temperature. Filtert nach Messwerttyp
  • sensorType string · Beispiel: sensorType=in100-q1-r-rc0i. Filtert nach Sensortyp (muss mit measure verwendet werden)
  • limit integer [ 1 .. 100 ] · Standard: 100 · Beispiel: limit=100. Maximale Anzahl zurückzugebender Ergebnisse
  • offset integer >= 0 · Standard: 0 · Beispiel: offset=0. Anzahl der zu überspringenden Ergebnisse (für die Paginierung)

Antworten

  • 200 · Historische Daten erfolgreich zurückgegeben
  • 400 · Ungültiger Request
  • 401 · Nicht autorisiert, Authentifizierung fehlgeschlagen
  • 403 · Zugriff verweigert, unzureichende Berechtigungen
  • 404 · Ressource nicht gefunden
  • 500 · Interner Serverfehler

get /devices/{deviceId}/history

Beispielantwort (granularity=raw):

{
  "data": [{}, {}, {}],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 96,
    "hasMore": true,
    "returned": 96
  },
  "granularity": "raw"
}

Hochfrequente Daten

Operationen für den Zugriff auf die CSV-Dateien mit hochfrequenten Gerätedaten.

Mit diesen Endpoints können Sie:

  • Die verfügbaren hochfrequenten CSV-Datendateien auflisten
  • Die CSV-Dateien über vorsignierte S3-URLs herunterladen
  • Dateien nach Datum, Stunde und Gerät filtern
  • Die täglichen Download-Kontingente überwachen

Hochfrequente CSV-Dateien auflisten

Gibt eine Liste der verfügbaren CSV-Dateien mit hochfrequenten Gerätedaten zurück, mit vorsignierten S3-URLs für den Download.

⚠️ Wichtig: Dieser Endpoint ist nur verfügbar, wenn Sie hochfrequente Geräte haben (z. B. Motorsensoren). Hat Ihr Tenant/Standort keine hochfrequenten Geräte, gibt die API die Fehlermeldung NoHighFrequencyDevices zurück.

System der hochfrequenten Daten:

  • CSV-Dateien werden automatisch jede Stunde (zur Minute 10) für die vorangegangene Stunde erstellt
  • Eine Datei pro Gerät und Stunde (nur wenn Daten vorhanden sind)
  • Die Dateien liegen in S3 und sind nach Tenant, Gerät, Datum und Stunde organisiert
  • Nur Geräte mit der Kennzeichnung highfrequency = true werden berücksichtigt

Datenaufbewahrung: Hochfrequente CSV-Datendateien sind 30 Tage verfügbar (wie Rohdaten).

Download-Kontingente:

  • Jeder Tenant hat ein tägliches Download-Limit (backup_hf_daily_download_limit)
  • Das Limit gilt gemeinsam für alle API-Keys/Nutzer innerhalb des Tenants
  • Das Kontingent wird um Mitternacht UTC zurückgesetzt
  • Jede Erzeugung einer vorsignierten URL zählt zum Tageslimit

Standardverhalten (ohne deviceId und ohne hour):

  • Gibt nur die jeweils neueste verfügbare Datei pro Gerät zurück (für das gewählte Datum, Standard: aktueller UTC-Tag)
  • Hält die Antworten klein und ist ideal für Clients mit täglicher Synchronisierung

Ganztagesmodus:

  • Um alle Dateien des Tages für alle Geräte abzurufen, verwenden Sie mode=day

Filter:

  • date: Filter nach einem bestimmten Datum (YYYY-MM-DD). Standard: aktueller Tag
  • hour: Filter nach einer bestimmten Stunde (0-23)
  • deviceId: Filter nach einem bestimmten Gerät (muss zu Ihrem Tenant gehören)
  • mode: latest (Standard) oder day

Antwortformat:

  • Die Dateien sind nach device_id und dann nach Stunde gruppiert
  • Jede Stunde enthält eine vorsignierte S3-URL (15 Minuten gültig)
  • Die Kontingentinformationen zeigen Tageslimit, Nutzung und verbleibende Downloads

Fehlerfälle:

  • Hat der Tenant/Standort keine hochfrequenten Geräte: gibt den Fehler "NoHighFrequencyDevices" zurück
  • Ist das Tageskontingent überschritten: gibt 429 Too Many Requests zurück
  • Gehört das Gerät nicht zum Tenant: gibt 403 Forbidden zurück

Authorization: ApiKeyAuth

Query-Parameter

  • date string ^\d{4}-\d{2}-\d{2}$ · Beispiel: date=2026-02-19. Datum, für das die hochfrequenten Datendateien abgefragt werden (Format YYYY-MM-DD). Standard: aktueller Tag (UTC)
  • hour integer [ 0 .. 23 ] · Beispiel: hour=15. Stunde, nach der die Dateien gefiltert werden (0-23). Beispiel: 15 für 15:00 Uhr
  • deviceId string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ · Beispiel: deviceId=ad:6a:f5:ae:c9:b5. Geräte-ID, nach der die Dateien gefiltert werden (Format MAC-Adresse). Hinweis: Das Gerät muss zu Ihrem Tenant gehören
  • mode string · Standard: "latest" · Enum: "latest" "day" · Beispiel: mode=latest. Antwortmodus: latest (Standard) gibt nur die neueste verfügbare Datei pro Gerät zurück; day gibt alle Dateien des gesamten Tages zurück (kann umfangreich sein)

Antworten

  • 200 · Liste der hochfrequenten Datendateien erfolgreich zurückgegeben
  • 400 · Ungültige Request-Parameter
  • 401 · Nicht autorisiert, Authentifizierung fehlgeschlagen
  • 403 · Zugriff verweigert, fehlende Berechtigung oder Gerät gehört nicht zum Tenant
  • 404 · Gerät nicht gefunden
  • 429 · Tägliches Download-Kontingent überschritten
  • 500 · Interner Serverfehler

get /backup_files_highfrequency

Beispielantwort (Erfolg mit Dateien):

{
  "files": {
    "ad:6a:f5:ae:c9:b5": {}
  },
  "quota": {
    "dailyLimit": 100,
    "usedToday": 3,
    "remaining": 97,
    "resetAt": "2026-02-20T00:00:00.000Z"
  }
}

Kostenlosen Test anfordern

Wir antworten innerhalb von einem Werktag. Unverbindlich.

Formular wird geladen…

Die über dieses Formular gesendeten Daten werden wie in unserer Datenschutzerklärung beschrieben verarbeitet. Das Formular wird von Tally gehostet.