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.
POST /api/v1/user/loginDer Antwort-Schlüssel heißt
token.Verwendung im Header:
Authorization: Bearer <token>
Basis-URLs
| Dienst | Basis-URL |
|---|---|
| Login | https://api-backend.juconn.io |
| Sensordaten | https://data-backend.juconn.io |
| Liegenschafts-Metadaten | https://metadata-backend.juconn.io |
Integrationsablauf
Standardablauf zum Abrufen von Sensordaten einer Liegenschaft:
Anmeldung
token.Anfrage-Parameter (Body)
| Feld | Typ | Beschreibung | |
|---|---|---|---|
| string | Pflicht | E-Mail-Adresse des Dashboard-Accounts | |
| password | string | Pflicht | Passwort des Dashboard-Accounts |
Antwort
| Feld | Typ | Beschreibung |
|---|---|---|
| token | string | JWT — als Bearer-Token bei allen weiteren Anfragen verwenden |
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"}'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
Gibt eine Liste aller verfügbaren Liegenschaften zurück. Die id aus der Antwort wird für den nächsten Schritt benötigt.
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"
}
]Gibt Metadaten einer Liegenschaft zurück — inklusive aller Sensor-IDs, die für den Sensordaten-Abruf benötigt werden.
Pfad-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| siteId | ObjectID | MongoDB ObjectID der Liegenschaft (aus GET /ext/site) |
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" }
]
}
]
}
]
}"Boilerladekreis"), wird dieser als Anzeigename verwendet — andernfalls die externalId. Siehe Sensor-Mapping.
Sensordaten (paginiert)
page=0 beginnen, dann page=1, page=2 usw. — wiederholen, bis das Daten-Array leer ist. Mit size die Seitengröße steuern.
Pfad-Parameter
| Parameter | Typ | Beschreibung |
|---|---|---|
| sensorId | ObjectID | MongoDB ObjectID des Sensors (aus GET /ext/site/{id}) |
Query-Parameter
| Parameter | Typ | Beispiel | Beschreibung | |
|---|---|---|---|---|
| start_date | ISO 8601 | Pflicht | 2026-05-01T00:00:00 | Beginn des Zeitraums |
| end_date | ISO 8601 | Optional | 2026-05-31T23:59:59 | Ende des Zeitraums |
| order | string | Optional | asc | asc oder desc |
| size | integer | Optional | 100 | Einträge pro Seite (Standard: 10) |
| page | integer | Pflicht | 0 | Seitenindex, beginnend bei 0 |
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}"#!/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
| Feld | Typ | Beschreibung |
|---|---|---|
| data | array | Liste der Messwerte dieser Seite |
| data[].value | number | Messwert des Sensors |
| data[].serverTimestamp | ISO 8601 | Zeitstempel der Messung (UTC) |
| totalElements | integer | Gesamtanzahl aller Einträge im gewählten Zeitraum |
| page | integer | Aktuelle Seitennummer (0-basiert) |
| pageSize | integer | Anzahl Einträge pro Seite |
ceil(totalElements / pageSize). Im obigen Beispiel: ceil(3100 / 10) = 310 Seiten.Sensor-Mapping — Namenslogik
external_id. Der angezeigte Name wird nach folgender Regel ermittelt:
→ Der individuelle Name wird als Anzeigename verwendet.
→ 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.
# 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_id | Controller external_id | Anzeigename (UI) |
|---|---|---|
| cir_pump_X_state | pumps | Zirkulationspumpe X Zustand |
| cir_pump_X_amp | pumps | Zirkulationspumpe X Wert |
| room_pump_X_state | pumps | Heizkreispumpe X Zustand |
| room_pump_X_amp | pumps | Heizkreispumpe X Wert |
| buffer_pump_X_state | pumps | Pufferladepumpe X Zustand |
| buffer_pump_X_amp | pumps | Pufferladepumpe X Wert |
| boiler_pump_X_state | pumps | Kesselkreispumpe X Zustand |
| boiler_pump_X_amp | pumps | Kesselkreispumpe X Wert |
| solar_pump_primary_X_state | pumps | Solarpumpe Primär X Zustand |
| solar_pump_primary_X_amp | pumps | Solarpumpe Primär X Wert |
| solar_pump_secondary_X_state | pumps | Solarpumpe Sekundär X Zustand |
| solar_pump_secondary_X_amp | pumps | Solarpumpe Sekundär X Wert |
| hot_water_charging_pump_X_state | pumps | Boilerladepumpe X Zustand |
| hot_water_charging_pump_X_amp | pumps | Boilerladepumpe X Wert |
| heat_pump_X_state | pumps | Wärmepumpe X Zustand |
| heat_pump_X_amp | pumps | Wärmepumpe X Wert |
| warm_water_pump_X_state | pumps | Warmwasserpumpe X Zustand |
| warm_water_pump_X_amp | pumps | Warmwasserpumpe 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_id | Controller external_id | Anzeigename (UI) |
|---|---|---|
| Warmwasser & Speicher | ||
| water_temp | warm_water_circulation_X | Warmwasser Zirkulation X |
| water_temp | warm_water_buffer_X | Warmwasser Puffer X |
| water_temp | warm_water_boiler_X | Warmwasser Boiler X |
| water_temp | warm_water_solar_X | Solarspeicher X |
| water_temp | warm_water_outlet_X | Warmwasser Auslass X |
| water_temp | custom_water_X | Benutzerdefiniertes Warmwasser X |
| Frischwasserstation | ||
| flow_temp | fresh_water_station_primary_X | Frischwasserstation Primär X Vorlauftemperatur |
| return_temp | fresh_water_station_primary_X | Frischwasserstation Primär X Rücklauftemperatur |
| spread_temp1 | fresh_water_station_primary_X | Frischwasserstation Primär X Spreizung |
| fresh_water_temp | fresh_water_station_primary_X | Frischwasserstation Primär X Warmwasser |
| Heizkreis | ||
| flow_temp | heater_cl_X | Heizkreis X Vorlauftemperatur |
| return_temp | heater_cl_X | Heizkreis X Rücklauftemperatur |
| spread_temp | heater_cl_X | Heizkreis X Spreizung |
| Kesselkreis | ||
| flow_temp | heater_bl_X | Kesselkreis X Vorlauftemperatur |
| return_temp | heater_bl_X | Kesselkreis X Rücklauftemperatur |
| spread_temp | heater_bl_X | Kesselkreis X Spreizung |
| flow_temp | heater_bl_secondary_X | Kesselkreis Sekundär X Vorlauftemperatur |
| return_temp | heater_bl_secondary_X | Kesselkreis Sekundär X Rücklauftemperatur |
| spread_temp | heater_bl_secondary_X | Kesselkreis Sekundär X Spreizung |
| Fernwärme | ||
| flow_temp | heater_dh_primary_X | Fernwärme Kreis Primär X Vorlauftemperatur |
| return_temp | heater_dh_primary_X | Fernwärme Kreis Primär X Rücklauftemperatur |
| spread_temp | heater_dh_primary_X | Fernwärme Kreis Primär X Spreizung |
| flow_temp | heater_dh_secondary_X | Fernwärme Kreis Sekundär X Vorlauftemperatur |
| return_temp | heater_dh_secondary_X | Fernwärme Kreis Sekundär X Rücklauftemperatur |
| spread_temp | heater_dh_secondary_X | Fernwärme Kreis Sekundär X Spreizung |
| Solarkreis | ||
| flow_temp | heater_sl_primary_X | Solarkreis Primär X Vorlauftemperatur |
| return_temp | heater_sl_primary_X | Solarkreis Primär X Rücklauftemperatur |
| spread_temp | heater_sl_secondary_X | Solarkreis Primär X Spreizung |
| flow_temp | heater_sl_secondary_X | Solarkreis Sekundär X Vorlauftemperatur |
| return_temp | heater_sl_secondary_X | Solarkreis Sekundär X Rücklauftemperatur |
| spread_temp | heater_sl_secondary_X | Solarkreis Sekundär X Spreizung |
| Pufferladekreis | ||
| flow_temp | heater_blc_X | Pufferladekreis X Vorlauftemperatur |
| return_temp | heater_blc_X | Pufferladekreis X Rücklauftemperatur |
| spread_temp | heater_blc_X | Pufferladekreis X Spreizung |
| flow_temp | heater_blc_secondary_X | Pufferladekreis Sekundär X Vorlauftemperatur |
| return_temp | heater_blc_secondary_X | Pufferladekreis Sekundär X Rücklauftemperatur |
| spread_temp | heater_blc_secondary_X | Pufferladekreis Sekundär X Spreizung |
| Boilerladekreis | ||
| flow_temp | heater_whlc_X | Boilerladekreis X Vorlauftemperatur |
| return_temp | heater_whlc_X | Boilerladekreis X Rücklauftemperatur |
| spread_temp | heater_whlc_X | Boilerladekreis X Spreizung |
| flow_temp | heater_whlc_secondary_X | Boilerladekreis Sekundär X Vorlauftemperatur |
| return_temp | heater_whlc_secondary_X | Boilerladekreis Sekundär X Rücklauftemperatur |
| spread_temp | heater_whlc_secondary_X | Boilerladekreis Sekundär X Spreizung |
| Solekreis | ||
| flow_temp | heater_brine_loop_X | Solekreis X Vorlauftemperatur |
| return_temp | heater_brine_loop_X | Solekreis X Rücklauftemperatur |
| spread_temp | heater_brine_loop_X | Solekreis X Spreizung |
| Wärmepumpe Kreis | ||
| flow_temp | heater_hpl_X | Wärmepumpe Kreis X Vorlauftemperatur |
| return_temp | heater_hpl_X | Wärmepumpe Kreis X Rücklauftemperatur |
| spread_temp | heater_hpl_X | Wärmepumpe Kreis X Spreizung |
| Hauptsammelkreis & Benutzerdefiniert | ||
| flow_temp | collection_loop_X | Hauptsammelkreis X Vorlauftemperatur |
| return_temp | collection_loop_X | Hauptsammelkreis X Rücklauftemperatur |
| spread_temp | collection_loop_X | Hauptsammelkreis X Spreizung |
| flow_temp | custom_loop_X | Benutzerdefinierter Kreis X Vorlauftemperatur |
| return_temp | custom_loop_X | Benutzerdefinierter Kreis X Rücklauftemperatur |
| spread_temp | custom_loop_X | Benutzerdefinierter Kreis X Spreizung |
Immoconn External API Dokumentation — liveapi.juconn.io / metadata-backend.juconn.io