sensorapi_influxtst/API_DOCUMENTATION.md

SensorAPI - API Dokumentation

Übersicht

Die SensorAPI ist eine REST-API zur Abfrage von Umweltsensordaten (Lärm, Feinstaub, Temperatur, Radioaktivität). Sie unterstützt sowohl InfluxDB 1.8 (InfluxQL) als auch InfluxDB 2.0 (Flux) sowie MongoDB für Metadaten.

Version: 1.4.1
Basis-URL: http://<host>:<port>/api/

---

Technologie-Stack

• Backend: Node.js mit Express.js
• Datenbanken:
  • InfluxDB 1.8/2.0 (Zeitreihendaten)
  • MongoDB (Sensor-Metadaten und -Eigenschaften)
• Sprachen: JavaScript (ES6 Module)
• Key Dependencies: axios, luxon, i18next, dotenv

---

Unterstützte Sensortypen

Typ	Beschreibung	Messgrößen
noise	Lärmsensoren	LA_max, LA_min, LA_eq, E10tel_eq
pm	Feinstaubsensoren	P1, P2, P0
thp	Temperatur/Luftfeuchte/Druck	temperature, humidity, pressure
radioactivity	Radioaktivitätssensoren	counts_per_minute

---

API Endpunkte

Alle Endpunkte folgen dem Schema: GET /api/<command>?<parameter>

1. getsensordata

Hauptendpunkt zum Abrufen von Sensordaten. Leitet je nach Sensortyp an spezialisierte Handler weiter.

Endpunkt: /api/getsensordata

Pflichtparameter:

• sensorid (int) - Eindeutige Sensor-ID

Optionale Parameter (abhängig vom Sensortyp):

Für Lärmsensoren (noise):

• data (string, default: 'live') - Art der Daten
• span (int, default: 1) - Zeitspanne in Tagen
• daystart (bool, default: null) - Start um 00:00:00 Uhr
• peak (int, default: 70) - Schwellenwert für Lärmspitzen in dB
• since (date, default: '1900-01-01T00:00:00Z') - Startdatum
• datetime (date, default: null) - Spezifisches Datum/Zeit
• long (bool, default: false) - Erweiterte Ausgabe
• sort (int, default: 1) - Sortierung (1=aufsteigend, -1=absteigend)
• csv (bool, default: false) - CSV-Ausgabe
• out (string, default: '') - Ausgabeformat

Für Radioaktivitätssensoren (radioactivity):

• what (string, default: 'day') - Art der Aggregation
• span (int, default: 1) - Zeitspanne in Tagen
• avg (int, default: 1) - Mittelwert-Intervall
• moving (bool, default: false) - Gleitender Mittelwert

Beispiel:

GET /api/getsensordata?sensorid=12345&span=7&peak=75

Antwort:

{
  "err": null,
  "values": [
    {
      "_time": "2025-11-04T10:00:00.000Z",
      "DNMS_noise_LA_max": 78.5,
      "DNMS_noise_LA_min": 45.2,
      "DNMS_noise_LA_eq": 65.3,
      "E10tel_eq": 72777980.45
    }
  ]
}

---

2. getactdata

Abrufen aktueller/historischer Rohdaten eines Sensors.

Endpunkt: /api/getactdata

Parameter:

• sensorid (int) - Sensor-ID
• span (int, optional) - Zeitspanne in Tagen
• datetime (date, optional) - Startdatum
• sort (int, optional) - Sortierung

Beispiel:

GET /api/getactdata?sensorid=12345&span=1

Antwort:

{
  "err": null,
  "values": [
    {
      "_time": "2025-11-04T10:00:00.000Z",
      "DNMS_noise_LA_max": 78.62,
      "DNMS_noise_LA_min": 47.36,
      "DNMS_noise_LA_eq": null,
      "E10tel_eq": 72777980.45
    }
  ]
}

---

3. getavgdata

Abrufen von Durchschnittswerten mit konfigurierbarem Zeitfenster.

Endpunkt: /api/getavgdata

Pflichtparameter:

• sensorid (int) - Sensor-ID

Optionale Parameter:

• span (int, default: 1) - Zeitspanne in Tagen
• datetime (date, default: null) - Startdatum
• avg (int, default: 10) - Mittelwert-Intervall in Minuten
• moving (bool, default: true) - Gleitender Mittelwert

Beispiel:

GET /api/getavgdata?sensorid=12345&span=7&avg=60&moving=true

Antwort:

{
  "data": {
    "start": "2025-10-28T10:00:00Z",
    "span": 7,
    "avg": 60,
    "moving": true,
    "count": 168,
    "values": [...]
  },
  "err": null
}

---

4. getlongavg

Langzeit-Durchschnittswerte über einen längeren Zeitraum.

Endpunkt: /api/getlongavg

Pflichtparameter:

• sensorid (int) - Sensor-ID

Optionale Parameter:

• span (int, default: 2) - Zeitspanne in Tagen

Beispiel:

GET /api/getlongavg?sensorid=12345&span=30

Antwort:

{
  "data": {
    "span": 30,
    "values": [
      {
        "_stop": "2025-11-04T00:00:00.000Z",
        "LA_max": 75.3,
        "LA_min": 42.1,
        "LA_eq": 63.8
      }
    ]
  },
  "err": null
}

---

5. getoneproperty

Abrufen der Eigenschaften eines Sensors (Metadaten, Standort, etc.).

Endpunkt: /api/getoneproperty

Pflichtparameter:

• sensorid (int) - Sensor-ID

Beispiel:

GET /api/getoneproperty?sensorid=12345

Antwort:

{
  "err": null,
  "props": {
    "_id": 12345,
    "name": [{"name": "Hauptstraße"}],
    "type": "noise",
    "location": [{
      "id": "loc_123",
      "loc": {
        "type": "Point",
        "coordinates": [9.123, 48.456]
      },
      "indoor": false
    }],
    "othersensors": [
      {"name": "PM Sensor", "sid": 12346}
    ]
  }
}

---

6. getmapdata

Abrufen von Sensordaten für Kartendarstellung mit geografischer Filterung.

Endpunkt: /api/getmapdata

Pflichtparameter:

• type (string) - Sensortyp (noise, pm, thp, radioactivity)

Optionale Parameter (einer muss angegeben werden):

• box (string) - Begrenzungsbox: "west,south,east,north"
• poly (JSON-Array) - Polygon-Koordinaten
• center (Array) - Mittelpunkt [lng, lat]
• distance (int, default: 10) - Radius in km (nur mit center)

Beispiel:

GET /api/getmapdata?type=noise&box=9.0,48.0,9.5,48.5

Antwort:

{
  "err": null,
  "options": {
    "lastdate": "2025-11-04T10:30:00.000Z",
    "count": 25,
    "data": "map"
  },
  "values": [
    {
      "location": [9.123, 48.456],
      "id": 12345,
      "name": "Hauptstraße",
      "indoor": false,
      "lastseen": "2025-11-04T10:25:00.000Z",
      "value": 75.3,
      "weeks": 0
    }
  ]
}

Wert-Kodierung:

• value >= 0: Aktueller Messwert
• value = -1: Daten älter als 2 Stunden
• value = -2: Daten älter als 7 Tage
• value = -3: Daten älter als 30 Tage
• value = -4: Daten älter als 365 Tage
• value = -5: Keine Daten vorhanden

---

7. getaddress

Geocoding: Koordinaten aus Adresse ermitteln.

Endpunkt: /api/getaddress

Parameter:

• address (string) - Adresse

Beispiel:

GET /api/getaddress?address=Hauptstraße+10,+Stuttgart

---

8. getcitycoords

Koordinaten einer Stadt abrufen.

Endpunkt: /api/getcitycoords

Parameter:

• city (string) - Stadtname

Beispiel:

GET /api/getcitycoords?city=Stuttgart

---

9. getakwdata

Abrufen von Atomkraftwerks-Daten (spezialisiert).

Endpunkt: /api/getakwdata

---

Zeitformat-Konvertierung

Die API akzeptiert verschiedene Zeitformate:

InfluxDB 2.0 (Flux) Format:

start: -7d
stop: now()

InfluxDB 1.8 (InfluxQL) Format:

now() - 7d
now()

Absolute Zeitangaben (ISO 8601):

2025-11-04T10:00:00.000Z

Wichtig: Bei der Verwendung von ISO-Zeitstempeln mit InfluxDB 1.8 werden diese automatisch in Anführungszeichen gesetzt.

---

Fehlerbehandlung

Alle Endpunkte geben Fehler im folgenden Format zurück:

{
  "err": "ERROR_CODE",
  "values": []
}

Häufige Fehlercodes:

• NODATA - Keine Daten gefunden
• SYNTAXURL - Ungültige Query-Syntax
• NOPROPSREAD - Eigenschaften konnten nicht gelesen werden
• NOPROPSFOUND - Keine Eigenschaften gefunden
• CMNDUNKNOWN - Unbekannter Befehl

---

Spezielle Berechnungen für Lärmdaten

Logarithmische Mittelwertbildung

Für Dezibel-Werte (LA_max) wird eine korrekte logarithmische Mittelwertbildung durchgeführt:

1. Konvertierung zu linear: E10tel = 10^(LA_max/10)
2. Arithmetischer Mittelwert: mean_E10tel = sum(E10tel) / count
3. Rückkonvertierung zu dB: n_AVG = 10 * log10(mean_E10tel)

Peak-Zählung

Bei getlongavg mit long=true werden Lärmspitzen über einem Schwellenwert gezählt:

{
  "_time": "2025-11-04T12:00:00.000Z",
  "peakcount": 13,
  "n_AVG": 78.51,
  "count": 18
}

---

Datenbank-Konfiguration

Umgebungsvariablen (.env)

# InfluxDB 1.8
INFLUXHOST=localhost
INFLUXPORT=8086
INFLUXUSER=username
INFLUXPASS=password
INFLUXDB=sensor_data

# InfluxDB 2.0
INFLUXTOKEN=your_token_here
INFLUXDATABUCKET=sensor_data
INFLUXORG=citysensor

# MongoDB
MONGOHOST=localhost
MONGOPORT=27017
MONGODB=sensordb

# Datenbank-Auswahl
DBASE=mongo  # oder 'influx'

---

Ausgabeformate

JSON (Standard)

Alle Endpunkte geben standardmäßig JSON zurück.

CSV (Optional)

Bei einigen Endpunkten kann csv=true übergeben werden:

GET /api/getsensordata?sensorid=12345&csv=true

---

Paginierung

Die API verwendet keine explizite Paginierung. Große Datenmengen sollten über span und datetime Parameter zeitlich eingeschränkt werden.

---

Rate Limiting

Aktuell ist kein Rate Limiting implementiert. Dies sollte auf Proxy/Load-Balancer-Ebene erfolgen.

---

Beispiel-Workflows

Workflow 1: Karte mit Lärmsensoren anzeigen

1. Sensoren in Gebiet abrufen:

   GET /api/getmapdata?type=noise&box=9.0,48.0,9.5,48.5
   

2. Details für einen Sensor abrufen:

   GET /api/getoneproperty?sensorid=12345
   

3. Historische Daten abrufen:

   GET /api/getactdata?sensorid=12345&span=7
   

Workflow 2: Lärmstatistik über eine Woche

1. Durchschnittswerte mit Lärmspitzen:

   GET /api/getsensordata?sensorid=12345&span=7&peak=70&long=true
   

2. Ergebnis analysieren:

   {
     "values": [
       {
         "_time": "2025-11-04T00:00:00.000Z",
         "peakcount": 13,
         "n_AVG": 78.51,
         "count": 1440,
         "LA_max_log_avg": 78.51
       }
     ]
   }
   

---

Internationalisierung

Die API unterstützt mehrere Sprachen über i18next:

• Deutsch (de)
• Englisch (en)

Fehlermeldungen werden automatisch in der gewünschten Sprache zurückgegeben.

---

Sicherheit

API-Key-Authentifizierung

Die API unterstützt API-Key-Authentifizierung für programmatischen Zugriff.

Aktivierung

1. API-Keys generieren:

   node generate-apikey.js 3
   

2. In .env konfigurieren:

   API_AUTH_REQUIRED=true
   API_KEYS=key1,key2,key3
   

3. Server neu starten

Verwendung

API-Keys können auf zwei Arten übergeben werden:

Option 1: HTTP-Header (empfohlen)

curl -H "X-API-Key: your-api-key-here" \
  "http://localhost:3000/api/getactdata?sensorid=12345"

Option 2: Query-Parameter

curl "http://localhost:3000/api/getactdata?sensorid=12345&apikey=your-api-key-here"

Beispiel mit JavaScript/Node.js

import axios from 'axios'

const API_KEY = 'your-api-key-here'
const BASE_URL = 'http://localhost:3000/api'

// Mit Header
const response = await axios.get(`${BASE_URL}/getactdata`, {
  params: { sensorid: 12345 },
  headers: { 'X-API-Key': API_KEY }
})

// Mit Query-Parameter
const response2 = await axios.get(`${BASE_URL}/getactdata`, {
  params: { 
    sensorid: 12345,
    apikey: API_KEY 
  }
})

Beispiel mit Python

import requests

API_KEY = 'your-api-key-here'
BASE_URL = 'http://localhost:3000/api'

# Mit Header
headers = {'X-API-Key': API_KEY}
response = requests.get(f'{BASE_URL}/getactdata', 
                       params={'sensorid': 12345},
                       headers=headers)

# Mit Query-Parameter
response2 = requests.get(f'{BASE_URL}/getactdata',
                        params={'sensorid': 12345, 'apikey': API_KEY})

Fehlermeldungen

401 Unauthorized - Kein API-Key angegeben:

{
  "err": "UNAUTHORIZED",
  "message": "API key required. Provide X-API-Key header or apikey query parameter."
}

403 Forbidden - Ungültiger API-Key:

{
  "err": "FORBIDDEN",
  "message": "Invalid API key"
}

Best Practices

• Niemals API-Keys im Code committen - verwenden Sie Umgebungsvariablen
• Verschiedene Keys für verschiedene Clients - ermöglicht granulare Kontrolle
• Keys regelmäßig rotieren - besonders nach Mitarbeiterabgängen
• HTTPS verwenden - schützt Keys bei Übertragung
• Keys sicher speichern - z.B. in Secret Management Systemen
• Logging aktivieren - überwachen Sie API-Zugriffe

Weitere Sicherheitsmaßnahmen

Für Produktionsumgebungen sollten zusätzlich implementiert werden:

• HTTPS erzwungen - verhindert Man-in-the-Middle-Angriffe
• CORS-Regeln konfiguriert - beschränkt Browser-Zugriffe
• Rate Limiting aktiviert - schützt vor Missbrauch
• IP-Whitelisting - zusätzliche Zugriffskontrolle
• Request-Logging - Audit-Trail für Compliance

---

Support und Weiterentwicklung

Für Fragen, Bugs oder Feature-Requests siehe die Projekt-Repository-Dokumentation.

Version History:

• 1.4.1: Unterstützung für InfluxDB 1.8 mit InfluxQL, logarithmische Mittelwertbildung für Lärmdaten