Navigation:

Liturgischer Kalender - API

Über diese API (Application Programming Interface, Programmierschnittstelle) können Daten des liturgischen Kalenders der römisch-katholischen Kirche im deutschen Sprachraum abgefragt und in andere Anwendungen eingebunden werden. Für die Nutzung durch andere Websites gilt die Bedingung des "fair use", d.h. Nutzung ist gestattet, soweit die Darstellung den Inhalt und seinen Zusammenhang nicht verfälscht, alle Abfragen durch menschliche Aktionen (z.B. Linkaufrufe auf einer Website) ausgelöst werden und jede einzelne dieser menschlichen Aktionen nicht mehr als zwei Abfragen der API bewirkt. Bei der Einbindung in Kalenderprogramme wird darum gebeten, die Zeitspanne für neues Laden nicht unter 24 Stunden einzustellen. Das Angebot ist nicht-kommerziell und kostenlos: Der Anbieter bemüht sich um die Korrektheit der Daten und die dauerhafte Verfügbarkeit des Angebots, übernimmt dafür jedoch keinerlei Garantie.

Zweck ist, die jeweils zum Zeitpunkt der Abfrage aktuellen liturgischen Daten zu bieten. Abfragen für vergangene Jahre liefern daher anachronistische Ergebnisse, so wie auch Kalender zukünftiger Jahre unter dem Vorbehalt etwaiger Änderungen durch die zuständigen kirchlichen Entscheidungsträger stehen.

1. Dateiformate

Diese Formate stehen für die Anzeige der Abfrageergebnisse zur Verfügung:

2. Aufruf der API

Es gibt zwei Formen des Aufrufs, die sich in der Art der Parameterübergabe unterscheiden:

2.1 Übergabe der Parameter mit der GET-Methode

Hierbei werden die Parameter so übergeben, wie es ein HTML-Formular mit method="GET" tut. Der http-Aufruf sieht dann so aus:

http://eucharistiefeier.de/lk/api.php?[Parametername]=[Wert](...)

Ein Beispiel:

http://eucharistiefeier.de/lk/api.php?format=html&info=wdtrlu&jahr=2025&monat=12&tag=8

Dies ist die flexiblere Methode, da hier alle Parameter wie gewünscht angegeben werden können.

2.2 Übergabe der Parameter im Dateinamen

Hier werden Parameter in den Dateinamen eingebaut:

http://eucharistiefeier.de/lk/api/lk[nav][info][jahr][monat][tag][kal].[format]

Alle Parameter sind, mit Ausnahme der Formatangabe (d.h. des Dateisuffixes), auch hier optional. Die Parameter jahr, monat und tag haben hier eine feste Anzahl von Stellen (4 bzw. 2); bei Angabe von Nullen werden jeweils die Default-Werte genommen.

Das obige Beispiel sieht in diesem Format so aus:

http://eucharistiefeier.de/lk/api/lkwdtrlu20251208.html

Nicht alle Parameter und Werte können auf diese Weise übermittelt werden. Ein Vorteil ist jedoch, dass manche Browser sich beim Herunterladen von Dateien hier leichter tun.

3. Die Parameter

Alle Parameter sind fakultativ (optional); fehlende Angaben werden durch (meist) sinnvolle Standardwerte ersetzt. Bei Parameterübergabe im Pfad sind die Parameter jahr und format obligatorisch. Für erste Versuche empfiehlt sich der Aufruf mit möglichst wenigen Parametern.

format Mögliche Werte sind html, xml, csv, ics (oder ical) und xcal (siehe Nr. 1). Default-Wert: html
jahr
monat
tag
Hiermit wird das gewünschte Datum angegeben (bei Angabe im Dateinamen müssen diese Zahlen 4- bzw. 2-stellig sein, insgesamt also 4, 6 oder 8 Ziffern angegeben werden).
Wird tag nicht angegeben, aber jahr und ggf. monat, dann werden die liturgischen Daten des entsprechenden Zeitraums zurückgegeben.
Für jahr sind Werte zwischen 1970 und 2037 gültig.
Um relative Angaben zu machen (z.B. einen Kalender des heutigen/morgigen Tags, des aktuellen oder des folgenden Monats oder Jahres abzufragen), sind der zu addierende Wert als Wert des betreffenden Parameters anzugeben und die übrigen beiden Parameter leer zu lassen. Bei Verwendung der GET-Methode können auch negative Werte verwendet werden. Wo bei der Angabe im URL die Jahres- und/oder Monatsangabe leer bleiben müsste, sind stattdessen 4 bzw. 2 Nullen anzugeben.
Zur Verdeutlichung siehe unten den Abschnitt mit Beispielen.
info Hiermit wird ausgewählt, welche Informationen über die einzelnen liturgischen Kalendertermine im Ergebnis dargestellt werden sollen. Jeder der folgenden Buchstaben steht für einen Typ von Informationen:
wWochentag (Sonntag, Montag, ...)
dDatum (z.B. 04.07.2025)
tTitel (Bezeichnung des liturgischen Termins)
rRang (H bzw. Hochfest, F bzw. Fest, G bzw. gebotener Gedenktag, g bzw. nicht gebotener Gedenktag)
gGrad (1 bis 13 - gibt die Rangfolge gemäß dem Calendarium Romanum an - hauptsächlich für die Fehlersuche relevant)
fLiturgische Farbe (w,r,v,g - erübrigt sich eventuell, falls per CSS die jeweilige Farbe als Hintergrund oder auf anderem Weg angezeigt wird)
lLesungen (hier werden die vorgesehenen Bibelstellen für die jeweilige Eucharistiefeier angegeben, inkl. Antwortpsalm und Evangelium)
uURL (hiermit wird ein Link zur entsprechenden Seite des Online-Schott eingefügt)
x(zusätzlich zu u) Im Link zum Online-Schott wird ein Deep-Link ohne Navigation verwendet.
Wird dieser Parameter nicht angegeben, dann gelten folgende Default-Werte in Abhängigkeit von format:
formatDefault-Wert für info
htmlwdtrl bei der Anzeige einzelner Tage
dtrfl bei Monats- oder Jahreskalendern
xml
csv
wdtrgflu
ics
ical
xcal
tr
desc Nur bei den Formaten isc, ical und xcal: Angaben, die im Feld "DESCRIPTION" des ical-Formates erscheinen sollen (anstatt in "SUMMARY"). Werte wie bei info (s.o.), mit Ausnahme von u und x. Default-Wert: (leer).
dup z/e - wenn an einem Tag mehrere liturgische Termine möglich sind, dann können diese (soweit möglich) zusammengefasst oder einzeln dargestellt werden. Default-Wert: z beim Format html, sonst e. (Bei Wiedergabe einzelner Tage im Format html hat dieser Parameter keine Wirkung.)
bahn j/n - entscheidet, ob an gebotenen Gedenktagen die Bahnlesungen (vom jeweiligen Wochentag) als "Tageslesungen" angezeigt werden sollen (sinnvoll nur, wenn Lesungen oder Links ausgegeben werden). Default-Wert: j.
css Nur beim Format html: - Hier kann der Name eines Stylesheets (CSS-Datei) angegeben werden, das zuvor über den Stylesheet-Editor hochgeladen bzw. online erstellt wurde.
icaldate Nur bei den Formaten ics, ical und xcal: Gibt an, ob und welche Uhrzeiten für die zu importierenden Termine verwendet werden sollen. Der Default-Wert se bedeutet, dass Start ("DTSTART") und Ende ("DTEND") auf uhrzeitlose Ganztagesangabe gesetzt werden. Wenn die Buchstaben "s" und "e" jeweils Uhrzeiten angehängt werden (ohne Zwischenraum wie in den Beispielen s7e8, s7e7:30 oder s7:30e19:30), dann wird damit im Terminkalender ein Zeitraum innerhalb des Tages. Die Angabe des Endes kann auch entfallen, womit ein punktueller Moment (Termin ohne Dauer) angegeben ist (korrekte Angaben sind daher auch z.B. s7:30 oder s).
kal Dient zur Abfrage der liturgischen Kalender von Teilkirchen. Wird hier ein nicht existierender Wert angegeben, dann werden (ohne Fehlermeldung!) die Daten des Regionalkalenders genommen.
nav Nur beim Format html: o/u/ou - gibt an, ob oben oder unten oder an beiden Stellen eine Navigationszeile hinzugefügt werden soll, mit der im Kalender vor und zurückgeblättert werden kann. Default: keine Navigationszeile.

3. Beispiele

3.1 Jahreskalender eines bestimmten Jahres als Internetseite

Gleichbedeutend können dafür folgende Aufrufe gewählt werden:

http://eucharistiefeier.de/lk/api.php?jahr=2025

http://eucharistiefeier.de/lk/api.php?jahr=2025&format=html&info=dtrfl&dup=z&bahn=j

http://eucharistiefeier.de/lk/api/lk2025.html

http://eucharistiefeier.de/lk/api/lkdtrfl2025.html

3.2 Aktueller Jahreskalender als Internetseite mit Navigationszeilen oben und unten

Gleichbedeutend können dafür folgende Aufrufe gewählt werden:

http://eucharistiefeier.de/lk/api.php?nav=ou

http://eucharistiefeier.de/lk/api.php?jahr=0&format=html&info=dtrfl&dup=z&bahn=j&nav=ou

http://eucharistiefeier.de/lk/api/lkou0000.html

http://eucharistiefeier.de/lk/api/lkoudtrfl0000.html

3.3 Aktueller Monatskalender als Internetseite

Gleichbedeutend können dafür folgende Aufrufe gewählt werden:

http://eucharistiefeier.de/lk/api.php?monat=0

http://eucharistiefeier.de/lk/api.php?monat=0&format=html&info=dtrfl&dup=z&bahn=j

http://eucharistiefeier.de/lk/api/lk000000.html

http://eucharistiefeier.de/lk/api/lkdtrfl000000.html

3.4 Liturgische Termine des heutigen Tages als Internetseite

Gleichbedeutend können dafür folgende Aufrufe gewählt werden:

http://eucharistiefeier.de/lk/api.php?tag=0

http://eucharistiefeier.de/lk/api.php?tag=0&format=html&info=wdtrl&bahn=j

http://eucharistiefeier.de/lk/api/lk00000000.html

http://eucharistiefeier.de/lk/api/lkwdtrl00000000.html

3.5 Liturgische Termine des morgigen Tages als Internetseite mit Navigationszeile oben

Gleichbedeutend können dafür folgende Aufrufe gewählt werden:

http://eucharistiefeier.de/lk/api.php?tag=1&nav=o

http://eucharistiefeier.de/lk/api.php?tag=1&format=html&info=wdtrl&bahn=j&nav=o

http://eucharistiefeier.de/lk/api/lko00000001.html

http://eucharistiefeier.de/lk/api/lkowdtrl00000001.html

3.6 Liturgische Termine eines bestimmten Tages, ohne Lesungen, mit Link auf Online-Schott

Gleichbedeutend können dafür folgende Aufrufe gewählt werden:

http://eucharistiefeier.de/lk/api.php?jahr=2025&monat=12&tag=13&format=html&info=wdtru&bahn=j

http://eucharistiefeier.de/lk/api/lkwdtru20151213.html

3.7 Verwendung eines eigenen Stylesheets

Abfrage derselben Daten wie unter 3.6, aber mit eigenem Stylesheet mit Namen "gelb" (das zuvor über den Stylesheet-Editor hochgeladen bzw. online erstellt worden sein muss):

http://eucharistiefeier.de/lk/api.php?jahr=2025&monat=12&tag=13&format=html&info=wdtru&bahn=j&css=gelb

3.8 ICAL-Datei des nächsten Jahres (mit Standardvorgaben)

Gleichbedeutend können dafür folgende Aufrufe gewählt werden:

http://eucharistiefeier.de/lk/api.php?jahr=1&format=ics

http://eucharistiefeier.de/lk/api.php?jahr=1&format=ics&info=tr&dup=e&icaldate=se

http://eucharistiefeier.de/lk/api/lk0001.ics

http://eucharistiefeier.de/lk/api/lktr0001.ics

3.9 ICAL-Datei des laufenden Jahres, mit Lesungen und liturgischer Farbe in DESCRIPTION, mit Links

http://eucharistiefeier.de/lk/api.php?format=ics&info=tru&desc=fl

http://eucharistiefeier.de/lk/api.php?jahr=0&format=ics&info=tru&dup=e&desc=fl&icaldate=se

3.10 API-Zugriff per PHP

Um die Kalenderdaten durch einen anderen Server abfragen und weiterverarbeiten zu lassen, kann dies beispielsweise (für die Daten eines einzelnen Tages) per PHP so geschehen:

<?php

  $lkh=fopen('http://www.eucharistiefeier.de/lk/api.php?format=csv&tag=0&info=wdtrgflu&dup=e&bahn=j','r');

  if($lkh) {

    # Array mit Namen der Spalten (keys)
    # Derzeit: Index wtag datum tl bem l1 ap l2 ev farbe datei grad rang
    $ka=fgetcsv($lkh,9999,"\t");

    while(!feof($lkh)) {

      # Array mit Inhalten der Spalten
      $la=fgetcsv($lkh,9999,"\t");

      # Abbruch wenn Dateiende
      if($la===false) break;

      # Array mit den Spaltennamen als Schlüssel
      $lka=array_combine($ka,$la);

      # Einzelne Werte herausholen (weitere analog)
      $Titel=$lka['tl'];
      $Farbe=$lka['farbe'];

      # Weiterverarbeitung ...
      echo "<p>$Titel (Farbe: $Farbe)</p>";

    }

    fclose($lkh);

  }
  else {
    echo "<p>Fehler beim Lesen der Kalenderdaten</p>\n";
  }

?>

Damit der Zugriff der Funktion fopen auf die externe Ressource gelingt, muss er in der PHP-Konfiguration freigegeben sein (ab PHP 4.0.4 geht das mit dem Eintrag "allow_url_fopen = On" in php.ini).

4. Eigene Daten einbeziehen (lit. Kalender von Teilkirchen)

4.1 Aktueller Jahreskalender des Erzbistums Köln als Internetseite mit Navigationszeilen oben und unten

Gleichbedeutend können dafür folgende Aufrufe gewählt werden:

http://eucharistiefeier.de/lk/api.php?kal=koeln&nav=ou

http://eucharistiefeier.de/lk/api.php?kal=koeln&jahr=0&format=html&info=dtrfl&dup=z&bahn=j&nav=ou

http://eucharistiefeier.de/lk/api/lkou0000koeln.html

http://eucharistiefeier.de/lk/api/lkoudtrfl0000koeln.html

Welche Kalender derzeit zur Verfügung stehen, ist über die Seite Erweiterte Abfrage zur erfahren. Zur Eingabe eigener Kalenderdaten siehe die Seite Kalender von Teilkirchen bearbeiten.


Petition zur Einheitsübersetzung

eucharistiefeier.de  -  Fragen und Rückmeldungen bitte an: Hatto v. Hatzfeld -  Impressum