Immoconn External API

Diese Dokumentation beschreibt die öffentliche External API der Immoconn-Plattform. Sie umfasst den Login sowie die Endpunkte zum Abrufen von Liegenschafts-Metadaten und paginierten Sensormesswerten.

Alle Beispiele verwenden curl und können direkt im Terminal ausgeführt werden.

Authentifizierung

Alle Endpunkte sind durch einen Bearer JWT gesichert. Das Token wird einmalig über den Login-Endpunkt bezogen und anschließend bei jedem Request im HTTP-Header mitgesendet.

🔑
Token beziehen: POST /api/v1/user/login
Der Antwort-Schlüssel heißt token.
Verwendung im Header: Authorization: Bearer <token>

Basis-URLs

DienstBasis-URL
Loginhttps://api-backend.juconn.io
Sensordatenhttps://data-backend.juconn.io
Liegenschafts-Metadatenhttps://metadata-backend.juconn.io

Integrationsablauf

Standardablauf zum Abrufen von Sensordaten einer Liegenschaft:

1
Anmelden
→ JWT-Token
2
Liegenschaften auflisten
→ siteId
3
Liegenschaft abrufen
→ sensorIds
4
Sensordaten laden
→ Seite 0, 1, 2…

Anmeldung

POST /api/v1/user/login JWT-Token beziehen
💡
Gleiche Zugangsdaten wie beim Dashboard-Login. Das zurückgegebene Token steht im Feld token.

Anfrage-Parameter (Body)

FeldTypBeschreibung
emailstringPflichtE-Mail-Adresse des Dashboard-Accounts
passwordstringPflichtPasswort des Dashboard-Accounts

Antwort

FeldTypBeschreibung
tokenstringJWT — als Bearer-Token bei allen weiteren Anfragen verwenden
curl
curl -s -X POST https://api-backend.juconn.io/api/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"email": "benutzer@beispiel.de", "password": "passwort"}'
bash — Token direkt in Variable speichern
JWT_TOKEN=$(curl -s -X POST https://api-backend.juconn.io/api/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"email": "benutzer@beispiel.de", "password": "passwort"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

echo "Token: $JWT_TOKEN"

Response Body

{
  "token":         "<JWT-Token — für Bearer-Authentifizierung verwenden>",
  "refresh_token": "<Refresh-Token — zum Erneuern des JWT>",
  "token_type":    "Bearer",
  "email":         "benutzer@beispiel.de",
  "firstname":     "Max",
  "lastname":      "Mustermann",
  "active":        true,
  "_id":           "5e8d74aeca900e0006fcb4cd",
  "customer_id":   "6581fd6760d46c001733cd40",
  "created_time":  "2020-04-08T06:52:30.086",
  "updated_time":  "2026-05-28T14:47:51.238",
  "last_login":    "2026-05-28T14:47:51.235"
}

Liegenschaften

GET /api/v1/ext/site Alle Liegenschaften auflisten
🔑
Bearer-Token erforderlich. Kein Anfrage-Body notwendig.

Gibt eine Liste aller verfügbaren Liegenschaften zurück. Die id aus der Antwort wird für den nächsten Schritt benötigt.

curl
JWT_TOKEN="<token>"

curl -X GET https://metadata-backend.juconn.io/api/v1/ext/site \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Response Body

[
  {
    "name":    "Muster Str. 1, Unterföhring",
    "address": "Muster Str. 1, Unterföhring 875774",
    "id":      "6583fc7f60d46c00173e43bb"
  },
  {
    "name":    "Muster Str. 2, Unterföhring",
    "address": "Muster Str. 2, Unterföhring 875774",
    "id":      "6583fc7f60d46c00173e43bc"
  }
]
GET /api/v1/ext/site/{siteId} Liegenschaft & Sensor-IDs
🔑
Bearer-Token erforderlich.

Gibt Metadaten einer Liegenschaft zurück — inklusive aller Sensor-IDs, die für den Sensordaten-Abruf benötigt werden.

Pfad-Parameter

ParameterTypBeschreibung
siteIdObjectIDMongoDB ObjectID der Liegenschaft (aus GET /ext/site)
curl
JWT_TOKEN="<token>"
SITE_ID="6583fc7f60d46c00173e43bb"

curl -X GET "https://metadata-backend.juconn.io/api/v1/ext/site/${SITE_ID}" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Response Body

Die Antwort enthält die vollständige Struktur der Liegenschaft mit allen Gateways, Controllern und Sensoren. Die id der gewünschten Sensoren wird für den Sensordaten-Abruf benötigt.

{
  "name":    "Muster Str. 1, Unterföhring",
  "address": "Muster Str. 1, Unterföhring 875774",
  "id":      "6583fc7f60d46c00173e43bb",
  "gateways": [
    {
      "name":     "JUC",
      "serialNo": "JUC",
      "id":       "6583fadf60d46c00173e3be9",
      "controllers": [
        {
          "name":       "warm_water_1",
          "externalId": "warm_water_1",
          "id":         "6583fadf212ff43e3f161b2b",
          "sensors": [
            {
              "name":       "Warm Water Temperature",
              "externalId": "water_temp",
              "id":         "6583fadf212ff43e3f161b2c"
            }
          ]
        },
        {
          "name":       "heater_cl_1",
          "externalId": "heater_cl_1",
          "id":         "6583fadf212ff43e3f161b2f",
          "sensors": [
            { "name": "Flow Temperature",   "externalId": "flow_temp",   "id": "6583fadf212ff43e3f161b30" },
            { "name": "Return Temperature", "externalId": "return_temp", "id": "6583fadf212ff43e3f161b31" },
            { "name": "Spread Temperature", "externalId": "spread_temp", "id": "6583fadf212ff43e3f161b32" }
          ]
        },
        {
          "name":       "Boilerladekreis",
          "externalId": "heater_cl_2",
          "id":         "6583fadf212ff43e3f161b37",
          "sensors": [
            { "name": "Flow Temperature",   "externalId": "flow_temp",   "id": "6583fadf212ff43e3f161b38" },
            { "name": "Return Temperature", "externalId": "return_temp", "id": "6583fadf212ff43e3f161b39" },
            { "name": "Spread Temperature", "externalId": "spread_temp", "id": "6583fadf212ff43e3f161b3a" }
          ]
        },
        {
          "name":       "pumps",
          "externalId": "pumps",
          "id":         "6583fadf212ff43e3f161b3b",
          "sensors": [
            { "name": "Circulation Pump State", "externalId": "cir_pump_state",  "id": "6583fadf212ff43e3f161b3c" },
            { "name": "Circulation Pump Amp",   "externalId": "cir_pump_amp",    "id": "6583fadf212ff43e3f161b3d" },
            { "name": "Room Pump State",        "externalId": "room_pump_state", "id": "6583fadf212ff43e3f161b3e" },
            { "name": "Room Pump Amp",          "externalId": "room_pump_amp",   "id": "6583fadf212ff43e3f161b3f" }
          ]
        }
      ]
    }
  ]
}
💡
Namenslogik: Hat ein Controller oder Sensor einen individuellen Namen (z.B. "Boilerladekreis"), wird dieser als Anzeigename verwendet — andernfalls die externalId. Siehe Sensor-Mapping.

Sensordaten (paginiert)

GET /api/v1/ext/sensor/{sensorId} Zeitreihendaten seitenweise
🔑
Bearer-Token erforderlich.
Paginierung: Mit page=0 beginnen, dann page=1, page=2 usw. — wiederholen, bis das Daten-Array leer ist. Mit size die Seitengröße steuern.

Pfad-Parameter

ParameterTypBeschreibung
sensorIdObjectIDMongoDB ObjectID des Sensors (aus GET /ext/site/{id})

Query-Parameter

ParameterTypBeispielBeschreibung
start_dateISO 8601Pflicht2026-05-01T00:00:00Beginn des Zeitraums
end_dateISO 8601Optional2026-05-31T23:59:59Ende des Zeitraums
orderstringOptionalascasc oder desc
sizeintegerOptional100Einträge pro Seite (Standard: 10)
pageintegerPflicht0Seitenindex, beginnend bei 0
curl — einzelne Seite
JWT_TOKEN="<token>"
SENSOR_ID="692ad0dd20e75a6abefc9465"

curl -X GET \
  "https://data-backend.juconn.io/api/v1/ext/sensor/${SENSOR_ID}?start_date=2026-05-01T00%3A00%3A00&end_date=2026-05-31T23%3A59%3A59&order=asc&size=100&page=0" \
  -H "Authorization: Bearer ${JWT_TOKEN}"
bash — alle Seiten automatisch durchlaufen
#!/bin/bash
JWT_TOKEN="<token>"
SENSOR_ID="692ad0dd20e75a6abefc9465"
START_DATE="2026-05-01T00%3A00%3A00"
END_DATE="2026-05-31T23%3A59%3A59"
SEITENGROESSE=100
SEITE=0
AUSGABEDATEI="sensor_${SENSOR_ID}.jsonl"

echo "Lade Sensordaten für ${SENSOR_ID} ..."
> "${AUSGABEDATEI}"

while true; do
  ANTWORT=$(curl -s -X GET \
    "https://data-backend.juconn.io/api/v1/ext/sensor/${SENSOR_ID}?start_date=${START_DATE}&end_date=${END_DATE}&order=asc&size=${SEITENGROESSE}&page=${SEITE}" \
    -H "Authorization: Bearer ${JWT_TOKEN}")

  ANZAHL=$(echo "${ANTWORT}" | python3 -c "
import sys, json
d = json.load(sys.stdin)
print(len(d.get('data', [])))
" 2>/dev/null || echo "0")

  if [ "${ANZAHL}" -eq "0" ]; then
    echo "Fertig. Letzte Seite: ${SEITE}."
    break
  fi

  echo "${ANTWORT}" >> "${AUSGABEDATEI}"
  echo "  Seite ${SEITE}: ${ANZAHL} Einträge"
  SEITE=$((SEITE + 1))
done

echo "Gespeichert: ${AUSGABEDATEI}"

Response Body

{
  "data": [
    { "value": 44.0, "serverTimestamp": "2026-04-01T00:08:25.435Z" },
    { "value": 44.3, "serverTimestamp": "2026-04-01T00:23:29.156Z" },
    { "value": 44.2, "serverTimestamp": "2026-04-01T00:38:30.639Z" },
    { "value": 43.0, "serverTimestamp": "2026-04-01T00:53:31.620Z" },
    { "value": 44.8, "serverTimestamp": "2026-04-01T01:08:34.786Z" },
    { "value": 47.5, "serverTimestamp": "2026-04-01T01:23:36.295Z" },
    { "value": 45.6, "serverTimestamp": "2026-04-01T01:38:39.011Z" },
    { "value": 46.0, "serverTimestamp": "2026-04-01T01:53:41.237Z" },
    { "value": 44.2, "serverTimestamp": "2026-04-01T02:08:45.700Z" },
    { "value": 51.0, "serverTimestamp": "2026-04-01T02:23:47.775Z" }
  ],
  "totalElements": 3100,
  "page": 0,
  "pageSize": 10
}

Response Felder

FeldTypBeschreibung
dataarrayListe der Messwerte dieser Seite
data[].valuenumberMesswert des Sensors
data[].serverTimestampISO 8601Zeitstempel der Messung (UTC)
totalElementsintegerGesamtanzahl aller Einträge im gewählten Zeitraum
pageintegerAktuelle Seitennummer (0-basiert)
pageSizeintegerAnzahl Einträge pro Seite
💡
Die Gesamtanzahl der Seiten ergibt sich aus ceil(totalElements / pageSize). Im obigen Beispiel: ceil(3100 / 10) = 310 Seiten.

Sensor-Mapping — Namenslogik

Jeder Sensor und Controller besitzt eine external_id. Der angezeigte Name wird nach folgender Regel ermittelt:
Individueller Name vergeben
→ Der individuelle Name wird als Anzeigename verwendet.
🔤
Kein individueller Name
→ Die external_id wird direkt als Anzeigename verwendet.

Der Platzhalter X steht für eine laufende Nummer (1, 2, 3 …), wenn mehrere Instanzen desselben Typs vorhanden sind.

Beispiel
# Sensor external_id: "flow_temp"  |  Controller external_id: "heater_cl_1"
# Kein individueller Name → Anzeigename = "Heizkreis 1 Vorlauftemperatur"

# Sensor external_id: "flow_temp"  |  Controller external_id: "heater_cl_2"
# Individueller Name = "HK Wohnung OG" → Anzeigename = "HK Wohnung OG"

Sensor-Mapping — Pumpen

Bei allen Pumpen-Sensoren ist die Controller-external_id immer pumps.

Sensor external_idController external_idAnzeigename (UI)
cir_pump_X_statepumpsZirkulationspumpe X Zustand
cir_pump_X_amppumpsZirkulationspumpe X Wert
room_pump_X_statepumpsHeizkreispumpe X Zustand
room_pump_X_amppumpsHeizkreispumpe X Wert
buffer_pump_X_statepumpsPufferladepumpe X Zustand
buffer_pump_X_amppumpsPufferladepumpe X Wert
boiler_pump_X_statepumpsKesselkreispumpe X Zustand
boiler_pump_X_amppumpsKesselkreispumpe X Wert
solar_pump_primary_X_statepumpsSolarpumpe Primär X Zustand
solar_pump_primary_X_amppumpsSolarpumpe Primär X Wert
solar_pump_secondary_X_statepumpsSolarpumpe Sekundär X Zustand
solar_pump_secondary_X_amppumpsSolarpumpe Sekundär X Wert
hot_water_charging_pump_X_statepumpsBoilerladepumpe X Zustand
hot_water_charging_pump_X_amppumpsBoilerladepumpe X Wert
heat_pump_X_statepumpsWärmepumpe X Zustand
heat_pump_X_amppumpsWärmepumpe X Wert
warm_water_pump_X_statepumpsWarmwasserpumpe X Zustand
warm_water_pump_X_amppumpsWarmwasserpumpe X Wert

Sensor-Mapping — Temperaturen

Sensor-external_id: flow_temp, return_temp, spread_temp, water_temp, fresh_water_temp oder spread_temp1. Der Controller bestimmt den Kontext.

Sensor external_idController external_idAnzeigename (UI)
Warmwasser & Speicher
water_tempwarm_water_circulation_XWarmwasser Zirkulation X
water_tempwarm_water_buffer_XWarmwasser Puffer X
water_tempwarm_water_boiler_XWarmwasser Boiler X
water_tempwarm_water_solar_XSolarspeicher X
water_tempwarm_water_outlet_XWarmwasser Auslass X
water_tempcustom_water_XBenutzerdefiniertes Warmwasser X
Frischwasserstation
flow_tempfresh_water_station_primary_XFrischwasserstation Primär X Vorlauftemperatur
return_tempfresh_water_station_primary_XFrischwasserstation Primär X Rücklauftemperatur
spread_temp1fresh_water_station_primary_XFrischwasserstation Primär X Spreizung
fresh_water_tempfresh_water_station_primary_XFrischwasserstation Primär X Warmwasser
Heizkreis
flow_tempheater_cl_XHeizkreis X Vorlauftemperatur
return_tempheater_cl_XHeizkreis X Rücklauftemperatur
spread_tempheater_cl_XHeizkreis X Spreizung
Kesselkreis
flow_tempheater_bl_XKesselkreis X Vorlauftemperatur
return_tempheater_bl_XKesselkreis X Rücklauftemperatur
spread_tempheater_bl_XKesselkreis X Spreizung
flow_tempheater_bl_secondary_XKesselkreis Sekundär X Vorlauftemperatur
return_tempheater_bl_secondary_XKesselkreis Sekundär X Rücklauftemperatur
spread_tempheater_bl_secondary_XKesselkreis Sekundär X Spreizung
Fernwärme
flow_tempheater_dh_primary_XFernwärme Kreis Primär X Vorlauftemperatur
return_tempheater_dh_primary_XFernwärme Kreis Primär X Rücklauftemperatur
spread_tempheater_dh_primary_XFernwärme Kreis Primär X Spreizung
flow_tempheater_dh_secondary_XFernwärme Kreis Sekundär X Vorlauftemperatur
return_tempheater_dh_secondary_XFernwärme Kreis Sekundär X Rücklauftemperatur
spread_tempheater_dh_secondary_XFernwärme Kreis Sekundär X Spreizung
Solarkreis
flow_tempheater_sl_primary_XSolarkreis Primär X Vorlauftemperatur
return_tempheater_sl_primary_XSolarkreis Primär X Rücklauftemperatur
spread_tempheater_sl_secondary_XSolarkreis Primär X Spreizung
flow_tempheater_sl_secondary_XSolarkreis Sekundär X Vorlauftemperatur
return_tempheater_sl_secondary_XSolarkreis Sekundär X Rücklauftemperatur
spread_tempheater_sl_secondary_XSolarkreis Sekundär X Spreizung
Pufferladekreis
flow_tempheater_blc_XPufferladekreis X Vorlauftemperatur
return_tempheater_blc_XPufferladekreis X Rücklauftemperatur
spread_tempheater_blc_XPufferladekreis X Spreizung
flow_tempheater_blc_secondary_XPufferladekreis Sekundär X Vorlauftemperatur
return_tempheater_blc_secondary_XPufferladekreis Sekundär X Rücklauftemperatur
spread_tempheater_blc_secondary_XPufferladekreis Sekundär X Spreizung
Boilerladekreis
flow_tempheater_whlc_XBoilerladekreis X Vorlauftemperatur
return_tempheater_whlc_XBoilerladekreis X Rücklauftemperatur
spread_tempheater_whlc_XBoilerladekreis X Spreizung
flow_tempheater_whlc_secondary_XBoilerladekreis Sekundär X Vorlauftemperatur
return_tempheater_whlc_secondary_XBoilerladekreis Sekundär X Rücklauftemperatur
spread_tempheater_whlc_secondary_XBoilerladekreis Sekundär X Spreizung
Solekreis
flow_tempheater_brine_loop_XSolekreis X Vorlauftemperatur
return_tempheater_brine_loop_XSolekreis X Rücklauftemperatur
spread_tempheater_brine_loop_XSolekreis X Spreizung
Wärmepumpe Kreis
flow_tempheater_hpl_XWärmepumpe Kreis X Vorlauftemperatur
return_tempheater_hpl_XWärmepumpe Kreis X Rücklauftemperatur
spread_tempheater_hpl_XWärmepumpe Kreis X Spreizung
Hauptsammelkreis & Benutzerdefiniert
flow_tempcollection_loop_XHauptsammelkreis X Vorlauftemperatur
return_tempcollection_loop_XHauptsammelkreis X Rücklauftemperatur
spread_tempcollection_loop_XHauptsammelkreis X Spreizung
flow_tempcustom_loop_XBenutzerdefinierter Kreis X Vorlauftemperatur
return_tempcustom_loop_XBenutzerdefinierter Kreis X Rücklauftemperatur
spread_tempcustom_loop_XBenutzerdefinierter Kreis X Spreizung


Immoconn External API Dokumentation — liveapi.juconn.io / metadata-backend.juconn.io