Dieses Tool ermöglicht Pellethändlern den nächsten Liefertermin von Pelletkunden automatisiert abzuschätzen. Die Lieferhistorie des Kunden wird über die Schnittstelle an den Auswerteserver über einen API Call übermittelt und das Ergebnis zurückgeschickt. Dies erfolgt anonym, es wird weder eine Straße noch der Kundenname benötigt. Lediglich die Postleitzahl für die Zuordnung zu einer Wetterstation und die Pelletanlieferungen der jeweiligen Kundennummer sind notwendig.
Es handelt sich um eine Hochrechnung auf Basis vorheriger Lieferungen und den zurückliegenden Gradtagszahlen (GTZ) des jeweiligen Standorts. Der Kalkulation liegen die Gradtagzahlen der letzten 10 Jahre zugrunde, die mit den aktuellen Gradtagzahlen ständig aktualisiert werden. Somit kann ein lokales Temperaturprofil vom aktuellen Zeitpunkt und der Vergangenheit erstellt und berücksichtigt werden. Vergangene Lieferungen werden benötigt, um den Pelletverbrauch besser vorhersagen zu können. Dafür wird der jeweilige Pelletverbrauch mit dem Temperaturprofil des angegebenen vergangenen Zeitraums zusammengeführt.
Es kann somit der Zeitraum abgeschätzt werden, an dem das Lager keine Pellets mehr enthält und eine erneute Befüllung benötigt. Desto mehr zusammenhängende vorherige Lieferungen der jüngeren Vergangenheit eingetragen werden, umso genauer wird das Ergebnis. Bei möglichen Lücken in der Anlieferhistorie wird ein Plausibilitätstest vorgenommen und nur die Verbräuche in die Kalkulation einbezogen, die in einer festgelegten Bandbreite liegen.
Der Benutzer des Lieferterminrechners erhält einen Überblick, wann die nächste Befüllung des gewählten
Lagers bevorsteht, kann sich somit besser auf dieses vorbereiten und kann zum optimalen Zeitpunkt bestellen.
Somit kann ein lokales Temperaturprofil vom aktuellen Zeitpunkt und der Vergangenheit erstellt und
berücksichtigt werden. Vergangene Lieferungen werden benötigt, um den Pelletverbrauch besser vorhersagen zu können.
Dafür wird der jeweilige Pelletverbrauch mit dem Temperaturprofil des angegebenen vergangenen Zeitraums hinterlegt.
Alle Anfragen sind öffentliche GET- oder POST-Anfragen an den Auswerteserver /api/weather/v1/.
Diese API erfordert keine Authentifizierung.
Der Typ der Datenressourcen, die über die API-Aufrufe hinzugefügt / geändert / gelöscht werden können.
| Bedeutung Objekt | Beschreibung |
|---|---|
| Profil | Das Profil des Benutzers enthält Daten wie Postleitzahl, Lagerkapazität oder den Prozentsatz des verwendeten Warmwassers |
| Pelletlieferhistorie | Liste der Pelletlieferungen im Lager des Benutzers, erfordert sind Daten wie gelieferte Menge, vorhandene Menge im Lager und das Lieferdatum |
| Eigenschaft | Bedeutung Eigenschaft | Beschreibung |
|---|---|---|
| postal_code | Postleitzahl | Die Postleitzahl des Kundenlagers |
| name | Name oder Kundennummer | kurze Beschreibung dieses Profils, z.B. Name des Kunden oder Kundennummer |
| possible_quantity | Maximal mögliche Einblasmenge | Maximal in ein leeres Lager einbringbare Menge an Pellets (Kg) |
| use_warm_water | Warmwasserverbrauch |
Abfrage ob der Benutzer Pellets nur zur Raumwärme oder auch zum Erhitzen von Wasser verwendet
(Information nicht zwingend notwendig, bei Nichtübermittlung wird [1] angenommen)
|
| house_type | Haustyp |
Typ des Hauses, diese Information wird verwendet, um den %-Anteil der Pellets für die Warmwassererwärmung abzuschätzen
(Information nicht zwingend notwendig, bei Nichtübermittlung wird [1] angenommen)
|
| insulation_type | Isolierungsstand |
Stand der Hausisolierung, diese Information wird verwendet, um den %-Anteil der Pellets für die Warmwasserbereitung abzuschätzen
(Information nicht zwingend notwendig, bei Nichtübermittlung wird [2] angenommen)
|
| warm_water_percent | Anteil Warmwasserverbrauch | Manuell veränderter Prozentwert der Energie zur Erwärmung des Wassers für die Warmwassernutzung, wenn diese Information dem Benutzer bekannt ist. Akzeptierte Werte zwischen 0 und 50 %. |
| key | Schlüssel | Eindeutige Bezeichnung, der zur Identifizierung aller Objekte eines Profils verwendet wird (z.B. mehrere Objekte des gleichen Kunden). Dieser wird bei der Erstellung des Benutzerprofils erzeugt und danach in jedem API-Aufruf verwendet, der sich auf dieses Benutzerprofil bezieht. |
| station_name | Stationsname | Standort der Wetterstation, die für den Temperaturdatenverlauf verwendet wird. |
| pellet_loadings | Pelletbefüllungen | Liste der vergangenen Pelletbefüllungen des betrachteten Lagers des Benutzers. |
| estimated_quantity | Geschätzte Restmenge im Lager | Schätzung der vorhandenen Menge an Pellets im Lager des Benutzers zum Lieferzeitpunkt |
| estimated_interval | Geschätztes Lieferintervall | Zeitspanne, in der das Lager des Benutzers leer werden könnte. |
| estimated_kg_by_GTZ | Geschätzter Pelletverbrauch nach GTZ | Pelletsverbrauch in kg für jeden ℃ Differenz zwischen Außentemperatur und optimaler Heimtemperatur. |
| estimated_cleaning | Notwendige Komplettentleerung | Notwendigkeit einer Komplettentleerung mit ggf. Reinigung. |
POST /api/weather/v1/profile/create HTTP/1.1| Parameter | Bedeutung Parameter | Typ | Details | Beispiel |
|---|---|---|---|---|
| profile[postal_code] | Postleitzahl | String | erforderlich | 69939 |
| profile[name] | Name | String | erforderlich | Max Müller |
| profile[possible_quantity] | Maximal mögliche Einblasmenge | Dezimalzahl | erforderlich | 12500 |
| profile[use_warm_water] | Warmwasserverbrauch | Dezimalzahl | Optional | 1 |
| profile[house_type] | Haustyp | Dezimalzahl | Optional | 1 |
| profile[insulation_type] | Isolierungsstand | Dezimalzahl | Optional | 3 |
| profile[warm_water] | Anteil Warmwasser | Dezimalzahl | Optional | 20 |
Gibt den Schlüssel (KEY) und die ID des neu hinzugefügten Profils zurück. Alle anderen API-Aufrufe, die sich auf dieses Profil oder historische Lieferungen beziehen, verwenden den zurückgegebenen KEY-Wert.
Ein Fehler wird zurückgegeben, wenn der Vorgang nicht erfolgreich ist.
{
"success": 1,
"message": "",
"data": {
'key': '7424977757416718336_8bf8e3',
'id': 1898,
'station_name': Brilon,
'warm_water': 20,
},
}
POST /weather/v1/profile/update/key/{key} HTTP/1.1| Parameter | Bedeutung Parameter | Typ | Details | Beispiel |
|---|---|---|---|---|
| profile[postal_code] | Postleitzahl | String | erforderlich | 69939 |
| profile[name] | Name | String | erforderlich | Max Müller |
| profile[possible_quantity] | Maximal mögliche Einblasmenge | Dezimalzahl | erforderlich | 12500 |
| profile[use_warm_water] | Warmwasserverbrauch | Dezimalzahl | Optional | 1 |
| profile[house_type] | Haustyp | Dezimalzahl | Optional | 1 |
| profile[insulation_type] | Isolierungsstand | Dezimalzahl | Optional | 3 |
| profile[warm_water] | Anteil Warmwasser | Dezimalzahl | Optional | 20 |
Gibt den Namen der Wetterstation zurück, die für die Temperaturdaten und den Warmwasseranteil verwendet werden.
{
"success": 1,
"message": "",
"data": {
'warm_water': 20,
'station_name': 'Brilon',
},
}
GET /weather/v1/profile/get/key/{key} HTTP/1.1Gibt alle Daten des angeforderten Profils zurück. Gibt auch eine Schätzung zurück, wenn das möglich ist (genug Daten erforderlich).
Ein Fehler wird zurückgegeben, wenn der Vorgang nicht erfolgreich ist.
{
"success": 1,
"message": "",
"data": {
'id': 1898,
'postal_code': 59939,
'name': John Gone,
'possible_quantity': 12500,
'use_warm_water': 1,
'house_type': 1,
'insulation_type': 3,
'warm_water': 8,
'station_name': 'Brilon',
'pellet_loadings':[
0:{
'id': 789,
'delivered_quantity': 12000,
'storage_quantity': 200,
'delivered_at': 2019-07-12,
'is_ok': true,
},
1:{
'id': 791,
'delivered_quantity': 14000,
'storage_quantity': 1500,
'delivered_at': 2020-05-22,
'is_ok': true,
},
],
'estimated_quantity': 1845,
'estimated_interval': '19 Mai - 19 Iun 2021',
'estimated_kg_by_TGZ': 3.4,
'estimated_cleaning': false,
},
}
GET /weather/v1/profile/delete/key/{key} HTTP/1.1Gibt zurück, ob der Vorgang erfolgreich war: 1, wenn das Profil gelöscht wurde, sonst wird ein Fehler angezeigt.
{
"success": 1,
"message": "",
"data": {
},
}
POST /weather/v1/estimate-ww HTTP/1.1| Parameter | Typ | Details | Beispiel |
|---|---|---|---|
| profile[use_warm_water] | Dezimalzahl | Optional | 1 |
| profile[house_type] | Dezimalzahl | Optional | 1 |
| profile[insulation_type] | Dezimalzahl | Optional | 3 |
| profile[warm_water] | Dezimalzahl | Optional | 20 |
Gibt den Prozentsatz der Pellets zurück, die zur Erwärmung von Warmwasser verwendet wurden.
{
"success": 1,
"message": "",
"data": {
'warm_water': 20,
},
}
GET /weather/v1/profile/key/{key}/estimate HTTP/1.1Liefert eine Schätzung über die Restmenge im Lager, das ungefähre nächste Datum, wann das Lager leer sein wird und den durchschnittlichen Pelletverbrauch durch GTZ berechnet.
{
"success": 1,
"message": "",
"data": {
'estimated_quantity': 1845,
'estimated_interval': '19 Mai - 19 Iun 2021',
'estimated_kg_by_TGZ': 3.4,
'estimated_cleaning': true,
},
}
| Eigenschaft | Bedeutung Eigenschaft | Beschreibung |
|---|---|---|
| delivered_quantity | gelieferte Menge | Gelieferte Pelletmenge in kg. |
| storage_quantity | Restmenge | Vorhandene Pelletmenge im Lager des Kunden zum Zeitpunkt der Neubefüllung in kg. |
| delivered_at | Liefertermin | Datum der Lieferung, Format: JJJJ-MM-TT. |
| is_ok | Plausibilitätstest | Verbräuche die in einer festgelegten Bandbreite liegen. |
POST /weather/v1/profile/key/{key}/create-fill HTTP/1.1| Parameter | Bedeutung Parameter | Typ | Details | Beispiel |
|---|---|---|---|---|
| storage_fill[delivered_quantity] | Einblasmenge | Dezimalzahl | erforderlich | 11000 |
| storage_fill[storage_quantity] | Restmenge | Dezimalzahl | erforderlich | 750 |
| storage_fill[delivered_at] | Liefertermin | String | erforderlich | 2020-07-23 |
Gibt die ID der neu übermittelten Pelletlieferung zurück. Alle anderen API-Aufrufe, die sich auf diese Pelletlieferung beziehen, verwenden den zurückgegebenen ID-Wert zusammen mit dem Schlüssel (KEY) des Profils.
Ein Fehler wird zurückgegeben, wenn der Vorgang nicht erfolgreich ist.
{
"success": 1,
"message": "",
"data": {
'id': 25304,
'delivered_quantity': 11000,
'storage_quantity': 750,
'delivered_at': 2020-07-23,
},
}
POST /weather/v1/profile/key/{key}/update-fill/id/{id} HTTP/1.1| Parameter | Bedeutung Parameter | Typ | Details | Beispiel |
|---|---|---|---|---|
| storage_fill[delivered_quantity] | Einblasmenge | Dezimalzahl | erforderlich | 11000 |
| storage_fill[storage_quantity] | Restmenge | Dezimalzahl | erforderlich | 750 |
| storage_fill[delivered_at] | Liefertermin | String | erforderlich | 2020-07-23 |
Gibt Details zur Pelletladung zurück.
Ein Fehler wird zurückgegeben, wenn der Vorgang nicht erfolgreich ist.
{
"success": 1,
"message": "",
"data": {
'id': 25304,
'delivered_quantity': 11000,
'storage_quantity': 750,
'delivered_at': 2020-07-23,
},
}
GET /weather/v1/profile/key/{key}/get-fill/id/{id} HTTP/1.1Gibt die Details der Pelletlieferung zurück.
Ein Fehler wird zurückgegeben, wenn der Vorgang nicht erfolgreich ist.
{
"success": 1,
"message": "",
"data": {
'id': 25304,
'delivered_quantity': 11000,
'storage_quantity': 750,
'delivered_at': 2020-07-23,
},
}
GET /weather/v1/profile/key/{key}/delete-fill/id/{id} HTTP/1.1Gibt bei Löscherfolg die Zahl 1 zurück, wenn die Pelletladung gelöscht wurde, ansonsten eine Fehlermeldung.
{
"success": 1,
"message": "",
"data": {
},
}