Wochenspruch API

Die Wochenspruch-API gibt Zugriff auf die wichtigsten Daten zum Kirchenjahr im JSON-Format und stellt automatisch erzeugte Bilder zu den Wochensprüchen bereit. Als Datenbasis dient www.kirchenjahr-evangelisch.de.

Daten zum Kirchenjahr abfragen

Alle Daten zum Kirchenjahr lassen sich mit folgender URL abfragen:

https://wochenspruch.pfarr.tools/api/kirchenjahr

Daten zu einem bestimmten Datum lassen sich über /api/kirchenjahr/datum/<datum> abfragen.

Beispiel: 06.12.2024 (Nikolaustag)

https://wochenspruch.pfarr.tools/api/kirchenjahr/datum/2024-12-06

Wenn mehrere Proprien zu einem Tag gehören, werden alle zurückgegeben -- Beispiel: 24.12.2024

https://wochenspruch.pfarr.tools/api/kirchenjahr/datum/2024-12-24

Wenn kein Proprium zum Tag gehört, wird ein leeres Array zurückgegeben -- Beispiel 21.12.2024

https://wochenspruch.pfarr.tools/api/kirchenjahr/datum/2024-12-21

Soll bei solchen Tagen stattdessen der korrekte Wochenspruch zurückgegeben werden, ist stattdessen /api/kirchenjahr/woche/<datum> aufzurufen.

https://wochenspruch.pfarr.tools/api/kirchenjahr/woche/2024-12-21

Bilder mit Tages-/Wochensprüchen

Die Wochenspruch API stellt automatisch Bilder mit den Tagesversen bzw. Wochensprüchen bereit. Ein direkter Zugriff ist über die ID möglich, die von der API für das jeweilige Proprium zurückgegeben wird. Das Bild findet sich jeweils unter /spruch/<id>.jpg

Beispiel: 06.12.2024 (Nikolaustag)

https://wochenspruch.pfarr.tools/api/kirchenjahr/datum/2024-12-06 ergibt die ID 1353. Das Bild dazu lässt sich hier aufrufen: https://wochenspruch.pfarr.tools/spruch/1353.jpg

Alternativ lässt sich dasselbe Bild auch über das Datum aufrufen. Gehören mehrere Propria zum Datum, wird das erste verwendet.

https://wochenspruch.pfarr.tools/spruch/2024-12-06.jpg

Als letzte Möglichkeit lässt sich das Bild zu einem Proprium auch über einen "Slug", d.h. ein Textkürzel aufrufen. Dieses geht aus den Daten zum Proprium hervor. https://wochenspruch.pfarr.tools/api/kirchenjahr/datum/2024-12-06 ergibt als Slug "nikolaustag".

https://wochenspruch.pfarr.tools/spruch/nikolaustag.jpg

Hiermit kann besonders bei Tagen mit mehreren Proprien geziehlt ein bestimmtes Proprium abgerufen werden -- Beispiel: 24.11.2024 (Toten-/Ewigkeitssonntag)

https://wochenspruch.pfarr.tools/spruch/2024-11-24.jpg ergibt das erste Proprium (Totensonntag).

Dagegen ergibt https://wochenspruch.pfarr.tools/spruch/ewigkeitssonntag.jpg gezielt das gewünschte Proprium "Ewigkeitssonntag".

Bilder für soziale Medien

Alle oben genannten Links können auch Bilder in weiteren Formaten für soziale Medien produzieren. Die Wochenspruch API verwendet dann im Hintergrund smartcrop.js, um den besten Bildausschnitt zu wählen.

Für Instagram bietet sich beispielsweise ein quadratisches Format 1024x1024 an. Dieses erreicht man über /spruch/insta/<id>.jpg. Alle oben genannten Varianten (Datum, "Slug", usw. funktionieren auch hier.

Das aktuelle Bild für Instagram sieht z.B. so aus:

https://wochenspruch.pfarr.tools/spruch/insta/2024-11-18.jpg

Für Stories auf Instagram, Facebook oder für den Status auf WhatsApp eignet sich am besten ein Bild im Hochformat 1024x1920. Dieses erreicht man über /spruch/story/<id>.jpg. Alle oben genannten Varianten (Datum, "Slug", usw. funktionieren auch hier.

Das aktuelle Bild für die Story sieht z.B. so aus:

https://wochenspruch.pfarr.tools/spruch/story/2024-11-18.jpg

Aktuelle Bilder

Das Bild für heute

https://wochenspruch.pfarr.tools/spruch/2024-11-18.jpg

Nächste Bilder

https://wochenspruch.pfarr.tools/spruch/2024-11-20.jpg

https://wochenspruch.pfarr.tools/spruch/2024-11-24.jpg

https://wochenspruch.pfarr.tools/spruch/2024-11-24.jpg

https://wochenspruch.pfarr.tools/spruch/2024-12-01.jpg

https://wochenspruch.pfarr.tools/spruch/2024-12-06.jpg

https://wochenspruch.pfarr.tools/spruch/2024-12-08.jpg

https://wochenspruch.pfarr.tools/spruch/2024-12-15.jpg

Entwicklung

Die Wochenspruch API ist Teil von pfarr.tools und wurde von Pfr. Christoph Fischer entwickelt. Der Code steht unter der GPL 3.0+ Lizenz auf Codeberg bereit.

Bei der Entwicklung wurde darauf geachtet, möglichst sparsam auf die Datenquelle kirchenjahr-evangelisch.de zuzugreifen. Das Programm holt sich die Liste der Proprien aus den dort bereitgestellten Kalenderdateien und von der Startseite kirchenjahr-evangelisch.de. Weiter gehende Detaildaten werden über einen Cron-gesteuerten Scheduler und den CLI-Befehl artisan import:details abgerufen (jeweils ein Proprium pro Aufruf). Dabei werden Details für denselben Feiertag in anderen Jahren gleich automatisch mit aufgefüllt.