Aufruf mit -m - also NUR Mongo

Docs angepasst
2023-12-17 14:16:37 +01:00
parent fb076fd21d
commit 4f19f9973a
3 changed files with 360 additions and 6 deletions
--- a/docs/Laerm_API.md
+++ b/docs/Laerm_API.md
@@ -0,0 +1,255 @@
+# Lärm-API
+rxf 2023-11-29
+
+Über diese API können Lärm-Daten für alle Sensoren direkt aus der Datenbank ausgelesen werden.  Es existieren verschiedene Aufrufe.  
+Im folgenden wird der HOST, auf dem das Programm läuft (der Docker-Container *noise*) als **\<host\>** dargestellt.
+
+### Live - Messdaten
+#### Aufruf
+<https://\<host\>/api/getsensordata?sensorid=xxx&csv=true&span=xxx&datetime=xxxx&pretty>  
+oder ohne Parameter  
+<https://\<host\>/api/getsensordata>
+
+#### Parameter
+Alle Parameter sind optional und werden mit sinnvollen Defaults belegt, wenn sie fehlen.  
+
+  * ***sensorid:***  Nummer des Sensors, für den die Daten abgerufen werden sollen. Ist der Sensor nicht in der Datenbank, wird ein leeres Werte-Array zurückgegeben. Default = 1 (Sensor 1 existiert nicht, also wird bei fehlender Sensornummer ein leeres Array zurück gegeben)
+  * ***span:***  Zeitspanne in Tagen, für die die Daten ausgegeben werden. Default = 1, max = 30.
+  * ***datetime*** Zeitpunkt, ab dem die Ausgabe beginnen soll. Die Zeitangabe erfolgt im ISO8601-Format (also YYY-MM-HHThh:mmZ). 
+    * Ist dieser Wert angegeben, so gilt für die zu berechnende Zeitspanne:  
+    Startzeitpunkt = ***datetime***,  Endzeitpunkt = ***datetime + span (Tage)***  
+    * Ist dieser Wert  **nicht** angegeben, so berechnet sich die Zeitspanne zu:  
+    Startzeitpunkt = ***aktuelle Zeit - span (Tage)***, Endzeitpunkt = ***aktuelle Zeit***  
+  * ***csv:*** Ist ***csv=true*** angegeben, so werden die Daten als CSV-Datei ausgegeben. Ohne das ***csv*** werden die Daten als JSON ausgegeben.  Wird bei JSON-Ausgabe noch der Parameter **pretty** angegeben, so werden die JSON-Daten in einem gut lesbaren Format ausgegeben.
+    
+    
+#### Ausgabe
+Das Ausgabe-Format ist entweder ein JSON-Dokument oder eine CSV-Datei.  
+Das JSON-Dokument hat z.B. folgenden Aufbau:
+
+```
+{
+  "err": null,
+  "options": {
+    "sid": 37833,
+    "indoor": 0,
+    "span": 1,
+    "start": "2023-11-28T14:21:21Z",
+    "data": "live",
+    "count": 73
+  },
+  "values": [
+    {
+      "datetime": "2023-11-29T10:55:56Z",
+      "LA_min": 35.94,
+      "LA_max": 47.12,
+      "LAeq": 39.74,
+      "E10tel_eq": 9418.895965228417
+    },
+    {
+      "datetime": "2023-11-29T11:07:47Z",
+      "LA_min": 36.45,
+      "LA_max": 52,
+      "LAeq": 41.53,
+      "E10tel_eq": 14223.287871228213
+    },
+	...
+	]
+}
+```
+und als CSV-Datei:
+
+```
+datetime,LAeq,LAmax,LAmin,"10^(LAeq/10)"
+2020-08-10T09:37:29,52.5,68.75,39.58,177827.94100389228
+2020-08-10T09:39:59,44.84,67.48,39.21,30478.94989627983
+2020-08-10T09:42:31,51.68,64.79,39.58,147231.25024327193
+2020-08-10T09:45:02,44.43,56.95,39.46,27733.20104651838
+2020-08-10T09:47:32,50.15,64.87,38.95,103514.2166679343
+2020-08-10T09:50:03,47.17,58.74,39.78,52119.47111050811
+...
+2020-08-11T09:31:00,55.05,71.6,40.13,319889.51096913975
+2020-08-11T09:33:31,53.91,66.21,40.62,246036.76041476274	
+```
+
+### Auswertungen der Messdaten
+------------------
+#### Aufruf
+<https://\<host\>/api/getsensordata?sensorid=xxx&data=xxx&peak=70&csv=true&span=xxx&datetime=xxxx&pretty>  
+
+#### Parameter
+Die Parameter sind die gleichen wie oben und optional.
+Als zusätzlicher Parameter kommt hier ***data*** hinzu. Darüber wird ausgewählt, welche Auswertung verwendet werden soll.
+
+Die Bedeutung der einzelnen Werte für ***data***:
+
+* ***data=live***: Ergibt die identische Ausgabe wie oben, d.h. data=live kann auch weggelassen werden.
+* ***data=havg***: Ausgabe der Stunden-Mittelwerte. In der Augabe wird die Anzahl der Überschreitungen (als ***peakcount***) des Lärm-Pegels über einen bestimmten db-Wert (default = 70) angegeben. Mit dem Parameter ***peak=xxx*** kan dieser db-Wert eingestellt werden.
+* ***data=davg***: Ausgabe der Tages-Mittelwerte. Für die Spitzenwert-Überschreitungen (***peakcount***) gilt das Gleiche wie bei Stundenmittel.
+* ***data=daynight***: Ausgabe der Tages- und der Nacht-Mittelwerte. Die Tagesmittel werden von 6:00 bis 22:00 Uhr und die Nachtmittel von 22:00 bis 6:00 Uhr berechnet.
+* ***data=lden***: Ausgabe des LDEN-Mittelwertes. Hier wird der Tag weiter aufgeteilt: Tag (D) ist von 6:00 bit 18:00 Uhr, Abend (E) ist von 18:00 bis 22:00 Uhr und Nacht (N) geht von 22:00 bis 6:00 Uhr. Die einzelnen Mittelwerte werden noch unterschiedlich bewertet und daraus dann der gesamte Mittelwert (der LDEN) berechnet.
+
+#### Ausgabe
+Hie sind die Augaben ebenfalls als JSON-Dokument oder als CSV-Datei (mit der Option ***csv=true***) abrufbar.  
+
+Stundenmittel (JSON):
+
+```
+{
+  "err": null,
+  "options": {
+    "sid": 37833,
+    "indoor": 0,
+    "span": 7,
+    "start": "2023-11-22T14:30:08Z",
+    "data": "havg",
+    "peak": 70,
+    "count": 168
+  },
+  "values": [
+    {
+      "peakcount": 0,
+      "datetime": "2023-11-24T00:00:00Z",
+      "n_AVG": 38.42796079826682
+    },
+    {
+      "peakcount": 0,
+      "datetime": "2023-11-24T01:00:00Z",
+      "n_AVG": 37.946929500486355
+    },
+	....
+	]
+}
+	
+```
+Stundenmittel (CSV):
+
+```
+datetime,n_AVG,peakcount
+2020-07-11T22:00:00Z,42.760062147998624,0
+2020-07-11T23:00:00Z,40.712802683893074,0
+2020-07-12T00:00:00Z,40.71753006698157,1
+2020-07-12T01:00:00Z,39.25606411190053,0
+```
+
+Tagesmittel (JSON):
+
+```
+{
+  "err": null,
+  "options": {
+    "sid": 37833,
+    "indoor": 0,
+    "span": 30,
+    "start": "2023-10-30T00:00:00Z",
+    "data": "davg",
+    "peak": 70,
+    "count": 30
+  },
+  "values": [
+    {
+      "datetime": "2023-11-24T00:00:00Z",
+      "n_AVG": 43.21691983032072,
+      "peakcount": 39
+    },
+    {
+      "datetime": "2023-11-25T00:00:00Z",
+      "n_AVG": null,
+      "peakcount": 7
+    },
+	...
+  ]
+}
+```
+Tagesmittel (CSV):
+
+```
+datetime,n_AVG,peakcount
+2020-07-11T00:00:00Z,41.698517715727675,0
+2020-07-12T00:00:00Z,47.33575272178947,32
+2020-07-13T00:00:00Z,54.63937702461399,94
+```
+
+Tag-Nacht-Mittel (JSON)
+
+```
+{
+  "err": null,
+  "options": {
+    "sid": 37833,
+    "indoor": 0,
+    "span": 30,
+    "start": "2023-10-30T00:00:00Z",
+    "data": "daynight",
+    "count": 30
+  },
+  "values": [
+    {
+      "datetime": "2023-11-24T00:00:00Z",
+      "n_dayAVG": 43.900464786300105,
+      "n_nightAVG": 40.851023645531406
+    },
+    {
+      "datetime": "2023-11-25T00:00:00Z",
+      "n_dayAVG": null,
+      "n_nightAVG": null
+    },
+	...
+  ]
+}
+
+```
+Tag-Nacht-Mittel (CSV)
+
+```
+datetime,n_dayAVG,n_nightAVG
+2020-07-11T22:00:00Z,0,40.93231330612532
+2020-07-12T06:00:00Z,49.14770564689205,46.99391595352652
+2020-07-13T06:00:00Z,56.305828057753864,64.57989823641728
+2020-07-14T06:00:00Z,63.62474952627255,43.17808436755339
+...
+```
+
+LDEN (JSON)
+
+```
+{
+  "err": null,
+  "options": {
+    "sid": 37833,
+    "indoor": 0,
+    "span": 30,
+    "start": "2023-10-30T00:00:00Z",
+    "data": "lden",
+    "count": 30
+  },
+  "values": [
+    {
+      "datetime": "2023-11-24T00:00:00Z",
+      "lden": null
+    },
+    {
+      "datetime": "2023-11-25T00:00:00Z",
+      "lden": null
+    },
+	...
+  ]
+}
+```
+LDEN (CSV)
+
+```
+datetime,lden
+2020-07-11T22:00:00Z,46.161208717927906
+2020-07-12T06:00:00Z,53.79509744837196
+2020-07-13T06:00:00Z,69.9515379149476
+2020-07-14T06:00:00Z,62.02707812443635
+2020-07-15T07:00:00Z,56.98105132364213
+```
+#### Daten abspeichern
+Um die ausgelesenen Messdaten in eine Datei abzuspeichern, kann am Einfachsten das Programm **curl** verwendet werden. Sollen z.B. die aktuellen Daten des Sensors *37833* als JSON in die Datei **sensor_37833.json** gespeichert werden, so sieht der Aufruf folgendermaßen aus:
+
+~~~~
+curl -o sensor_37833.json "https://<host>/api/getsensordata?sensorid=37833"  
+~~~~
+Entprechendes gilt für die anderen Auswertungen.