WasteCalendar API
Zahlreiche Städte und Gemeinden verwenden bereits unseren digitalen Abfallkalender und integrieren diesen entweder in ihre eigene Homepage oder in eine Bürger-App um Abfuhrtermine online oder auf dem Smartphone bereitzustellen. Mit der Web-API können auch Sie unsere Technologie mit ihren Abfuhrterminen in ihr System integrieren. In dieser Anleitung zeigen wir Ihnen, welche Komponenten Sie für die Integration benötigen.
Grundsätzlich verwenden wir nur Standard-Webtechnologien. Unser sog. Webkit beinhaltet sowohl eine HTML-Oberfläche zum Auswählen von Adressdaten und zur Darstellung von Abfuhrterminen und eine Standard-JavaScript-Datei in der die Abfragen zu unserem WebService implementiert ist. Das Webkit verwendet keine iframes und ausschließlich von Standard-Browsern unterstützte Basistechnologien und kann deshalb mühelos in jedes Content Management System integriert werden.
Externe Bibliotheken (im Webkit enthalten)
- jquery
- bootstrap
- json2html
- jquery-combobox
- momentJS
Das Styling des Frontends beruht derzeit auf bootstrap und jquery. Beachten Sie, dass unsere Stylesheets möglicherweise Einflüsse auf Ihr Content Management Systemen oder auch umgekehrt die Designvorlage aus ihrem CMS Einfluss auf die Darstellung unserer Kalenderkomponenten nehmen könnte. Selbstverständlich können Sie unseren Stylesheet gerne nach Ihren Wünschen an Ihre Design anpassen.
Suchfilter
Das mit dem Webkit mitgelieferte Beispiel beinhaltet zwei Oberflächen für den allgemeinen Integrationsfall. Die zwei Oberflächen unterscheiden sich in ihren Benutzerauswahlmöglichkeiten in den Formularen:
Zonenbasiert: bei der ersten Oberfläche können Kalender, Zonen und Fraktionen ausgewählt werden.
Datei:Wastecalendar-ui-zone.png
Adressbasiert: bei der zweiten Oberfläche können Kalender, Orte, Adressen (Straße + Hausnummer) sowie Fraktionen ausgewählt werden.
Datei:Wastecalendar-ui-address.png
Die Formulardaten für die Auswahlfelder werden über Webservice-Calls befüllt.
Die Abfallarten mit den dazugehörigen Abfuhrterminen werden auf unserem Server aufgrund der Benutzerauswahl im Formular evaluiert und je nach OutputType in Form eines JSON-Arrays, als Downloadlink für eine CSV-, PDF- oder iCal-Datei zurückgegeben.
Die Suchfilter werden beim Laden der Seite und bei der Auswahl einzelner Felder über verschiedene WebService-Anfragen befüllt. Um den WebService nutzen zu können, müssen Sie in allen nachfolgenden URLs an der Stelle „KUNDE“ jeweils ihren von infeo zugewiesenen Kundenbezeichner einfügen.
Abfragen der öffentlich verfügbaren Kalender
https://services.infeo.at/awm/api/KUNDE/wastecalendar/calendars [GET]
Mit dieser Abfrage erhalten Sie ein Array aller zur Zeit veröffentlichen Kalender. Mit der id des Kalenders führen Sie dann weitere Abfragen aus.
[
{
"id": 241,
"lastChange": "2021-04-14T09:32:48+02:00",
"name": "2021",
"from": "2021-01-01T00:00:00+01:00",
"until": "2021-12-31T00:00:00+01:00",
"created": "2021-03-25T11:01:41+01:00",
"availableFrom": "2021-03-25T00:00:00+01:00",
"availableUntil": "2021-12-31T00:00:00+01:00",
"isDefault": true
}
]
Zonenbasierte Kalender
Zonenbasierte Kalender sind nicht über Ortsnamen und Adressen aufgebaut, sondern nur in Abfuhrgebiete (sog. Zonen) eingeteilt. In der Regel werden solche Zonen wiederum über regional wohldefinierte Bereiche definiert, wie z.B. Ortschaften, Ortsteile oder geograpische Sinneinheiten, die jeder Bürger mit Hausverstand zurodnen kann (z.B. „Landeck nördlich vom Inn“). In vielen Fällen wird dem Abfuhrplan auch ein grafischer Lageplan der einzelnen Zonen beigelegt. Wenn Sie einen adressbasierten Kalender verwenden, können Sie zum Kapitel „Adressbasierte Kalender“ springen.
Abfragen der Zonen
Für den Fall, dass Sie einen zonenbasierten Abfallkalender verwenden, können Sie mit der folgenden Abfrage eine Liste aller im ausgewählten Kalender vorhandenen Zonen abfragen.
https://services.infeo.at/awm/api/KUNDE/wastecalendar/zones?calendarId=241 [GET]
[
{
„id“: 1462,
„lastChange“: „2021-04-14T09:37:15+02:00“,
„name“: „Zone A“,
„calendarId“: 45
},
{
„id“: 1463,
„lastChange“: „2021-04-14T09:37:15+02:00“,
„name“: „Zone B“,
„calendarId“: 45
]
In unserem Webkit wird nun die Auswahlliste (dropdown) für die Zone jeweils mit den id und name Feldern aus dem Response oben befüllt.
Abfragen der Abfallarten pro Zone
Wählt der Benuzter eine der Zonen aus, kann der nächste Request zum Abfragen der Abfallarten für die gewählte Zone erfolgen.
https://services.infeo.at/awm/api/KUNDE/wastecalendar/fractions?calendarId=241&zoneId=45 [GET]
[
{
„id“: 3,
„lastChange“: „2021-04-14T09:38:28+02:00“,
„name“: „Altpapier“,
„shortname“: „AP“,
„color“: -16736285,
„aloaId“: 5,
„colorHex“: „#009FE3“
},
{
„id“: 4,
„lastChange“: „2022-04-52T12:35:12+02:00“,
„name“: „Bio“,
„shortname“: „B“,
„color“: -1525225,
„aloaId“: 7,
„colorHex“: „#4412F3“,
}
]
Der Response enthält wiederum eine Liste mit allen Fraktionen, die in dieser Zone bedient werden. Der Benutzer kann im nächsten Schritt für seinen individuellen Abfallkalender auch einige Abfallarten entfernen, wenn diese für ihn nicht relevant sind.
Abholtermine für zonenbasierte Kalender
Anhand der konkreten Zone und optional gefilterten Abfallarten können die Abfuhrtermine geladen werden.
https://services.infeo.at/awm/api/KUNDE/wastecalendar/export?calendarId=241&
zoneId=45&fractionIds=3&fractionIds=4&outputType=json [GET]
Als Rückmeldung erhalten Sie ein Array mit den Abfuhrterminen und den jeweils am betreffenden Termin gesammelten Fraktionen.
[
{
„plannedCollection“: „2021-01-21T00:00:00+01:00“,
„fractions“:
[
{
„fractionName“: „Bio“,
„fractionShortname“: „B“,
„color“: -2560,
„colorHex“: „#FFF600“,
„colorText“: „#000000“
}
]
},
{
„plannedCollection“: „2021-02-18T00:00:00+01:00“,
„fractions“:
[
{
„fractionName“: „Bio“,
„fractionShortname“: „B“,
„color“: -2560,
„colorHex“: „#FFF600“,
„colorText“: „#000000“
}
]
}
]
Adressbasierte Kalender
Adressbasierte Kalender greifen auf die in den Sammelstellen der Tourenplanung hinterlegt Adressdaten zurück und bilden eine Regionalstruktur aus Ort, Straße und Hausnummer ab. Wurde ein Kalender ausgewählt können danach in einem sog. Drilldown-Verfahren die drei Hierarchiestufen abgefragt werden, beginnen mit den Ortsnamen.
Abfragen der Ortsnamen
https://services.infeo.at/awm/api/KUNDE/wastecalendar/cities?calendarId=241 [GET]
[
{
„id“: 548,
„lastChange“: „2021-04-14T09:42:51+02:00“,
„name“: „Igls“,
„zipcode“: null,
„country“: 20,
„calendarId“: 241
}
]
Der Response enthält ein Array von Ortschaften, deren id und Name in der Ortsauswahl (dropdown) angezeigt bzw. verknüpft werden.
Abfragen der Straßennamen
Wurde der Ortsname ausgewählt, kann die Liste mit den Straßen für die gewählte Ortschaft abgefragt werden.
https://services.infeo.at/awm/api/KUNDE/wastecalendar/streets?calendarId=241&cityId=547 [GET]
[
{
„id“: 125266,
„lastChange“: „2021-04-14T09:44:28+02:00“,
„name“: „Achselkopfweg“,
„cityId“: 547,
„calendarId“: 241
},
{
„id“: 125045,
„lastChange“: „2021-04-14T09:44:28+02:00“,
„name“: „Adamgasse“,
„cityId“: 547,
„calendarId“: 241
}
]
Der Response ist wiederum ein Array mit allen Straßenobjekten, von denen die id und der Name in der nächsten Auswahlliste (dropdown) als Werte für die Befüllung verwendet.
Abfragen der Hausnummern
Anhand des ausgewählten Kalenders, Ort und Straße können die Hausnummern geladen werden.
https://services.infeo.at/awm/api/KUNDE/wastecalendar/housenumbers?
calendarId=241&cityId=547&streetId=125266 [GET]
[ „1“, „3“, „5“, „6“, „8a“, „10/1“ ]
Der Response enthält ein Array aller Hausnummer, jedoch nicht mehr als Objektstrukturen sondern nur noch als Liste von String-Elementen (ggf. mit Subnummer und/oder Topnummer).
Abfragen der Abfallarten
Anhand des ausgewählten Kalenders und den Adressdaten (Ort, Straße, Hausnummer) können die für diese Adresse verfügbaren Abfallarten geladen werden.
[
{
„id“: 174,
„lastChange“: „2021-04-14T09:47:35+02:00“,
„name“: „LVP“,
„shortname“: „LVP“,
„color“: -2560,
„aloaId“: 8,
„colorHex“: „#FFF600“
}
]
Der Response ist wie beim zonenbasierten Kalender eine Liste mit allen Fraktionen, die an dieser Adresse verfügbar sind.
Abfragen der Abfuhrtermine
Nun da alle Informationen vorhanden sind (Kalender, Ort, Straße, Hausnummer, Abfallarten) können die Abfuhrtermine abgefragt werden.
[
{
„plannedCollection“: „2021-01-21T00:00:00+01:00“,
„fractions“:
[
{
„fractionName“: „Bio“,
„fractionShortname“: „B“,
„color“: -2560,
„colorHex“: „#FFF600“,
„colorText“: „#000000“
}
]
},
{
„plannedCollection“: „2021-02-18T00:00:00+01:00“,
„fractions“:
[
{
„fractionName“: „Bio“,
„fractionShortname“: „B“,
„color“: -2560,
„colorHex“: „#FFF600“,
„colorText“: „#000000“
}
]
}
]
Der Response beinhaltet wieder ein Array mit allen Abfuhrterminen für die gewählte Adresse und die gewählten Abfallarten.
Alternative Ausgabeformate
Unabhängig vom Kalendertyp können beim Laden der Abfuhrtermine verschieden Ausgabeformate angegeben werden. In den zuvor genannten Beispielen wurden nur die JSON-Daten abgefragt, um im Webkit die entsprechenden Formularfelder zu befüllen. Alternativ dazu stehen Ihnen folgende Formate zur Verfügung:
- outputType=json: Dieser outputType gibt die Abfuhrtermine als JSON zurück. Wenn kein outputType angegeben wird, wird json zurückgesendet.
- outputType=pdf: gibt einen Stream für eine PDF-Datei zurück.
- outputType=csv: gibt einen Stream für eine CSV-Datei zurück.
- outputType=ical: gibt einen Stream für eine iCalendar-Datei zurück.