APIs

Change language: EN

nächste Seite: Pinouts NodeMCU v2, v3

API Sensor.Community (aka dusti.api, ehemals Luftdaten.info)

Die API nimmt die Sensordaten entgegen und dient als Basis für die grafische Darstellung auf http://maps.sensor.community/ . Zudem werden die Daten der "öffentlichen" Sensoren einmal täglich (gegen 8:00 Uhr) als CSV exportiert und unter http://archive.sensor.community/ zur Verfügung gestellt.

API Madavi.de

Die API nimmt ebenfalls die Sensordaten entgegen und speichert diese in ein CSV-Dateien (jeweils eine Datei pro Sensor und Tag). Desweiteren werden die Daten in einer InfluxDB abgelegt und via Grafana grafisch aufbereitet. Das Dateiarchiv kann unter https://api-rrd.madavi.de/sensor/csvfiles.php abgerufen werden, die grafische Darstellung unter https://api-rrd.madavi.de/grafana/d/GUaL5aZMz/pm-sensors?orgId=1 .

OpenSenseMap

Opensensemap ist eine freie Plattform für offene Sensordaten. Webseite sowie API sind quelloffen. Neben zahlreichen Projekten, welche Daten an diese Plattform liefern, kann auch der Feinstaubsensor seine Daten dorthin übertragen. Nutzer können dort ihre Werte anzeigen und als Graph aufbereiten lassen. Eine dort erzeugte "Box" hat eine eigene ID, diese ist auf der Konfigurationsseite des Feinstaubsensors einzutragen. Danach ist der API-Punkt in der Konfiguration zu aktivieren.

An eigene API senden

Die Daten können mit dieser Funktion auf einem Webserver gespeichert werden. Der Menüpunkt "An eigene API senden" auf der Konfigurationsseite des Feinstaubsensors muss entsprechend aktiviert und die Zieladresse mit Server, Pfad, Port sowie optional Benutzer und Passwort eingetragen werden. Zum Speichern und späteren Auswerten der Daten steht ein einfaches PHP-Script bereit:

https://github.com/opendata-stuttgart/madavi-api/blob/master/data_simple.php

Das speichert die gelieferten Daten in einer täglichen .csv-Datei ab. Die Daten werden im .json-Format und nicht im $_post-Format geliefert! Dieses Script kann auch Grundlage zur Speicherung in einer eigenen Datenbank verwendet werden (selbst programmieren).

Issue #69 gibt weitere Hinweise und Codebeispiele für PHP:
https://github.com/opendata-stuttgart/meta/issues/69#issuecomment-314222830

Noch ein Beispiel: ein Python Script als Systemd Service empfängt die Daten und sendet sie an Domoticz:
https://github.com/joba-1/airrohr2domoticz

Hinweis: Wenn eine HTTPS-Verschlüsselung genutzt werden soll, muss dies über Port 443 geschehen. Das auf dem Server verwendete SSL-Zertifikat darf max. 2048 Bit groß sein, da der Speicher der NodeMCU nicht mehr verkraftet. Dabei werden (u.a. aus Performancegründen) nur folgende SSL/TLS ciphers unterstützt: TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA

InfluxDB

InfluxDB ist eine spezielle Datenbank für zeitbasierte Messungen oder Events. Ist ein eigener InfluxDB-Server vorhanden, können die Daten des Sensors auch direkt an diesen geschickt werden. Die Voreinstellungen müssen für eigene Anwendung entsprechend angepasst werden. (Server, Port, Pfad, Benutzer) Dabei muss beim Server lediglich die Adresse, ohne Zusätze wie HTTP oder HTTPS eingegeben werden, wobei letzteres eh nicht unterstützt wird.
Weitergehende Infos zu InfluxDB
https://www.influxdata.com/
(Für HTTPS gelten die gleichen Einschränkungen wie für "An eigene API senden")

Ausführlichere Beschreibung

API Sensor.Community (ehemals Luftdaten.info)

Für die NodeMCU wird als ID die chipID genutzt. Für andere Systeme setzt sich X-Sensor aus einem Namen für das System (z.B. raspi für Raspberry) und einer eindeutigen ID zusammen (Raspberry: Serial in /proc/cpuinfo) zusammen.

Beispiel POST für SDS011:
Header

Content-Type: application/json  
X-Pin: 1  
X-Sensor: esp8266-12345678  

Data

{
  "software_version": "your_version", 
  "sensordatavalues":[
    {"value_type":"P1","value":"66.04"},
    {"value_type":"P2","value":"53.32"}
  ]
}  

Beispiel POST für DHT22:
Header

Content-Type: application/json  
X-Pin: 7  
X-Sensor: esp8266-12345678  

Data

{
  "software_version": "your_version", 
   "sensordatavalues":[
     {"value_type":"temperature","value":"22.30"},
     {"value_type":"humidity","value":"34.70"}
  ]
}  

Andere Sensoren:
BMP180: value_types: temperature, pressure; X-Pin: 3
BME280: value_types: temperature, humidity, pressure; X-Pin: 11
PMS1003 - PMS 7003: value_types: P1 (PM10), P2 (PM2.5); X-Pin: 1

Die Adresse des API-Endpunkts zum Abliefern der Daten ist https://api.sensor.community/v1/push-sensor-data/ (bzw. https://api-rrd.madavi.de/data.php fuer Madavi.de). Für Madavi.de wird ein Präfix benötigt, BME_280 für BME280 Werte bzw. SDS_, siehe https://github.com/opendata-stuttgart/sensors-software/blob/master/airrohr-firmware/airrohr-firmware.ino#L4423 Beispiel:

{
  "software_version": "your_version", 
  "sensordatavalues":[
    {"value_type":"SDS_P1","value":"66.04"},
    {"value_type":"SDS_P2","value":"53.32"}
  ]
}  

API Endpunkte für den Abruf von Daten

V1

https://data.sensor.community/static/v1/data.json - alle Messwerte aller Sensoren der letzten 5 Minuten

https://data.sensor.community/airrohr/v1/filter/{query} - alle Messwerte der letzten 5 Minuten gefiltert nach

• type={sensor type} : komma-getrennte Liste von Sensortypen, z.B. SDS011,BME280
• area={lat,lon,distance} : alle Sensoren in einem Radius e.g. 52.5200,13.4050,10 (Berlin) - Bitte nur nutzen wenn unbedingt nötig und 'box' nicht möglich!!!
• box={lat1,lon1,lat2,lon2} : alle Sensoren in einem 'Rechteck' mit den angegebenen Koordinaten e.g. 52.1,13.0,53.5,13.5
• country={country code} : komma-getrennte Liste von Länder-Codes, z.B. BE,DE,NL

Wichtig: Der Client muss bei Anfragen einen User-Agent mitschicken. Am besten einen solchen, der uns bei Problemen mit einzelnen User-Agents einen Kontakt zur Quelle der Anfragen ermöglicht. (seit 04.11.2022)

https://data.sensor.community/airrohr/v1/sensor/{apiID}/ - alle Messwerte der letzten 5 Minuten für den Sensor mit der angegebenen API-ID (NICHT die chipID. API-ID kann auf der Karte bei Klick auf den Sensor gefunden werden).

V2

https://data.sensor.community/static/v2/data.json - average of all measurements per sensor of the last 5 minutes for all sensors.
https://data.sensor.community/static/v2/data.1h.json - average of all measurements per sensor of the last hour.
https://data.sensor.community/static/v2/data.24h.json - average of all measurements per sensor of the 24 hours.
https://data.sensor.community/static/v2/data.dust.min.json - same as data.json but dust sensors only.
https://data.sensor.community/static/v2/data.temp.min.json - same as data.json but temp./humidity/air pressure sensors only.