API (Premium Feature)

Aktive Premium-Benutzer haben Zugang zu unseren externen API-Endpunkten. Bevor Sie diese nutzen k├Ânnen, m├╝ssen Sie diese in den Einstellungen /setting/profile/api aktivieren. Obwohl sie auf Ihrer Profilebene verwaltet wird, ist die API auf Imkerei basis aktiv. Wenn Sie mehrere Imkereibetriebe verwalten, m├╝ssen Sie sie f├╝r jeden einzelnen Betrieb die API aktivieren, da Sie jedes Mal einen anderen Schl├╝ssel erhalten.

Kalender, iCal

Um Ihre Aufgaben, Zuchtereignisse und ToDo's in Ihren lokalen Kalender auf Ihrem Handy, Google Kalender oder Computer zu ├╝bertragen, k├Ânnen Sie unseren iCal-Endpunkt abonnieren. iCal ist ein standardisiertes Format, das von den meisten Kalenderanwendungen verstanden wird. Der Kalender wird automatisch aktualisiert, abh├Ąngig von Ihren Kalendereinstellungen, und zeigt Ihnen die vergangenen und zuk├╝nftigen Ereignisse der letzten 6 Monate an. Sie m├╝ssen jede Aufgabe separat abonnieren, z. B. F├╝tterung, Ernte, ToDo. Das Kalenderabonnement ist schreibgesch├╝tzt, d. h. Sie k├Ânnen keine Aufgabe in Ihrem Kalender bearbeiten.

Auf der Seite mit den API-Einstellungen k├Ânnen Sie die Endpunkt-URL f├╝r die Abonnements kopieren, sie sieht wie folgt aus https://api.btree.at/api/v1/external/ical/TASK_NAME/API_KEY.

Die folgenden Links helfen Ihnen bei der Einrichtung Ihres Abonnements:

Hinweis: Wenn Sie nur die iCal-Datei herunterladen, handelt es sich nicht um ein Live-Datenabonnement, sondern es werden Ihnen nur die aktuell heruntergeladenen Ereignisse angezeigt.

Stockwaagen

Zun├Ąchst m├Âchten wir erw├Ąhnen, dass wir selbst keine Bienenstockwaagen herstellen oder verkaufen. Diese API ist nur f├╝r Benutzer gedacht, die gerne selbst Hand anlegen. Unser ehemaliges Stockwaagensystem war sehr einfach aufgebaut (/HannesOberreiter/bScale) aber wir haben die Arbeit daran eingestellt, da es bereits eine F├╝lle von sehr guten alternativen Systemen auf dem Markt gibt. Wenn Sie ein professionelles Setup ben├Âtigen, empfehlen wir den deutschen Hersteller Wolf-Waagen und wenn Sie Open Source und Basteln m├Âgen, empfehlen wir HiveEyes Community, beide haben ihre eigene Hardware- und Softwarel├Âsungen. Unsere Imkerei-App ist nicht mit keinem externen Stockwaagen System kompatibel, au├čer man modifiziert selbst die Daten├╝bertragung. Durch die F├╝lle an angeboten und Systemen ist ein Support von externen Waagen nur schwer durchzuf├╝hren, zweitens haben die meisten Waagen Hersteller bereits sehr gute Softwarel├Âsungen im Angebot.

Um die API zu aktivieren, m├╝ssen Sie zun├Ąchst eindeutige Identifikatoren erstellen. Dies k├Ânnen Sie in der Stockwaagen Tabelle /table/scale_data mit der Dropdown-Schaltfl├Ąche "Waagen" tun. Sie m├╝ssen f├╝r jede Stockwaage einen neuen Ident erstellen. Die derzeitige Grenze liegt bei 10 Stockwaagen mit je einer Daten├╝bertragung pro Stunde.

Die Informationen ├╝ber die zu ├╝bertragenden Daten werden mit Query Params angegeben um es m├Âglichst einfach zu machen. Auf der API-Einstellungsseite k├Ânnen Sie die Endpunkt-URL kopieren, um Daten mit einer einfachen GET-Anfrage zu senden: https://api.btree.at/api/v1/external/scale/IDENTIFIER/API_KEY?action=CREATE_DEMO&datetime=2022-09-08T09:50:23.990Z&weight=10.5&temp1=10.2&temp2=8.9&rain=15&hum=53

Die Abfrage-Parameter sind wie folgt definiert:

  • action: 'CREATE' or 'CREATE_DEMO' zum Testen, es werden keine Daten gespeichert aber man erh├Ąlt eine Server Antwort
  • datetime: Optional in ISO8601 Format, wenn nicht angegeben wird die Server UTC Zeit verwendet
  • weight: Optional, numerisch f├╝r das gemessene Gewicht
  • temp1: Optional, numerisch f├╝r Temperatur
  • temp2: Optional, numerisch f├╝r eine zweite Temperatur Messung (zB im Stock)
  • hum: Optional, numerisch f├╝r Luftfeuchtigkeit
  • rain: Optional, numerisch f├╝r Regenmenge
  • note: Optional, alphanumerischer text mit maximal 300 Zeichen, hier kann zB der Batterie Status oder Informationen zur Sendeleistung ├╝bertragen werden

Server Antworten

Erfolgreiches Ereignis:

{
  "datetime": "2022-09-08 10:02:54",
  "weight": 10.5,
  "temp1": 10.2,
  "temp2": 8.9,
  "rain": 15,
  "humidity": 53,
  "note": "",
  "scale_id": 27, // your identifier ID on the server
  "id": 200977 // current entry
}

Error: Limit an Daten ├ťbertragungen erreicht:

{
  "statusCode": 429,
  "statusText": "Too Many Requests",
  "errors": "you have exceeded your request limit"
}

Error: API Key oder Ident is falsch oder nicht vorhanden, beides gibt die selbe Antwort

{
  "statusCode": 404,
  "statusText": "Not Found",
  "errors": {
    "type": "NotFound",
    "data": {}
  }
}

Error: Falscher Wert (zum Beispiel wurde hier 'weight' mit 'abc' ├╝bertragen)

{
  "statusCode": 400,
  "statusText": "Bad Request",
  "errors": [
    {
      "value": "abc",
      "msg": "Invalid value",
      "param": "weight",
      "location": "query",
      "msgTranslation": {
        "de": "Falscher Wert",
        "en": "Invalid value"
      }
    }
  ]
}
┬ę 2014-2022 - b.tree by Hannes Oberreiter