Der große Temperatur-Check

Die technische Dokumentation der Server-Schnittstelle

Einführende Informationen gibt es im Artikel Mitmachprojekt: Wie warm ist es in euren Büros?

Über diese URL können Sie die Temperatur übermitteln:

http://www.golem.de/projekte/ot/temp.php?

Sie können die URL so oft aufrufen, wie Sie es für notwendig halten. Im Rahmen unserer Auswertung ist aber eine Intervalldauer von 15 bis 30 Minuten vollkommen ausreichend.

Erforderliche GET-Parameter

Diese Parameter müssen Sie übergeben:

• temp - Temperatur in Celsius, z.B.: 20.75, Wertebereich: -20 bis 100
• dbg - Bestimmt, ob der Eintrag zu Testzwecken (dbg=1) dient, oder in die Auswertung (dbg=0) eingehen soll.

Optionale GET-Parameter

Die folgenden Parameter sind nicht unbedingt erforderlich, aber können die Datenauswertung verbessern und helfen zusätzliche Erkenntnisse zu gewinnen. Wir würden uns freuen, wenn sie wenigstens einen der Ortsparameter übergeben.

Wenn Sie einen der Parameter übergeben, muss der Wert trotzdem valide sein, auch wenn er optional ist.

• token - Eindeutiger Token zur Geräteerkennung, siehe Token-Generierung
• type - Zur Messung benutzte Plattform:
  • sbc - Raspberry Pi und vergleichbare Bastelrechner wie der Banana Pi
  • ard - Arduino-Platinen und vergleichbare Mikrocontroller-Systeme mit separatem Wifi- oder Ethernetmodul.
  • wifimuc - nackte Microcontroller mit integriertem Wlan-Modul, zum Beispiel ESP8266 oder Particle Photon.
  • other - Keines der oben genannten Systeme
• country - Land der Messung, zweistelliger Landescode (z.B.: country=DE)
• city - Stadt-/Gemeindename, beachten Sie, dass Sonderzeichen wie auch Leerzeichen Url-codiert werden müssen.
• zip - Postleitzahl
• lat - GPS-Angabe, Breitengrad (z.B.: lat=52,5192)
• long - GPS-Angabe, Längengrad (z.B.: long=13,4061)

Hinweis: Die GPS-Angaben werden bei der Speicherung auf 4 Nachkommastellen gekürzt, aus Datenschutzgründen empfehlen wir 3 Nachkommastellen.

Wir empfehlen, unseren URL-Generator zu benutzen, um einen korrekte URL zu erzeugen.

Beispiel-URLs

Minimale URL für Testzwecke:

http://www.golem.de/projekte/ot/temp.php?temp=21.235&dbg=1

Minimale URL für die reguläre Übermittlung:

http://www.golem.de/projekte/ot/temp.php?temp=21.235&dbg=0

URL mit Ortsinformationen und Typangabe:

http://www.golem.de/projekte/ot/temp.php?temp=21.235&dbg=0&type=sbc&country=DE&zip=10969&city=Berlin&lat=52.50&long=13.41

Rückgabe des URL-Aufrufs

Wird die URL aufgerufen, wird normalerweise kein Inhalt zurück geliefert. Ob der Aufruf erfolgreich war oder nicht, kann über den zurückgelieferten HTTP-Statuscode ermittelt werden:

• 200 - Erfolgreicher Aufruf
• 400 - Fehlerhafter Aufruf, ein erforderlicher Parameter fehlt oder einer der übergebenen Parameter enthält einen unzuläßigen Wert. Die Fehlerursache wird im HTTP Response Body angegeben.
• 500 - Interner Fehler, bitte wenden Sie sich in diesen Fall per Email an technik@golem.de.

Token-Generierung

Es ist uns nicht möglich, eine Temperaturmeldung einem konkreten Messgerät zu zu ordnen. Allerdings sind wir durchaus neugierig auf die konkreten Temperaturverläufe in einem Büro über den Tag. Deshalb kann hier optional ein Token für ein Messgerät generiert und mitgeschickt werden. Auf diese Weise können wir – unter Wahrung der Anonymität – die Temperaturangaben konkreten Geräten zuordnen.

Außerdem können Sie auf diese Weise selbst prüfen, welche Temperatur Ihr Gerät gesendet hat. Über die URL

http://www.golem.de/projekte/ot/check.php?token=<token>

erhalten Sie die zuletzt übermittelte Temperatur.

Die URL

http://www.golem.de/projekte/ot/validate.php?token=<token>

liefert den kleinsten und höchsten bislang erfassten Messwert, den ersten und letzten Messzeitpunkt sowie die bisherige Anzahl aller Messwerte.

Um ein Diagramm mit den Messwerten der letzten 7 Tage zu erhalten, kann folgende URL aufgerufen werden:

http://www.golem.de/projekte/ot/chart.php?token=<token>

URL-Generierung

Mit diesem Formular können Sie die URL generieren: