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.

Um einen Abfrage-Link nach Ihren Bedürfnissen zusammenzustellen, können Sie - neben der folgenden detaillierten Beschreibung - auch das Formular erweiterte Abfrage nutzen.

1. Dateiformate

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

Bei den Formaten html, xml, json, jsonarray und csv werden folgende Parameterbezeichnungen ausgegeben:

Beim Format html tauchen diese Bezeichnungen nur als CSS-Klassen im Quellcode auf (und eignen sich daher zur Formatierung mit CSS); beim Format csv stehen sie mit Kleinbuchstaben in der Kopfzeile; beim Format xml sind sie ebenfalls klein geschrieben.

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://www.eucharistiefeier.de/lk/api.php?[Parametername]=[Wert](...)

Ein Beispiel:

http://www.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://www.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://www.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, json, 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
json
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: fl. Wird - angegeben, entfällt das Feld „DESCRIPTION“ gänzlich.
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). Ebenso bestimmt dieser Parameter, ob eventuell mögliche Kommemorationen angegeben 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.
mg Hiermit kann die Ausgabe auf die wichtigeren Termine beschränkt werden. Anzugeben ist der Grad (1-13), bis zu dem die Termine ausgegeben werden sollen. Beispiel: Die Angabe 6 bedeutet, dass alle Termine mit Grad 1 bis 6 ausgegeben werden, d. h. alle Sonntage und höherrangigen Feste. Der Default-Wert 0 bedeutet, dass alle Termine ausgegeben werden.
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.
nav Nur beim Format json: o/u/ou - Der Wert o bewirkt, dass im JSON-Objekt zwei Eigenschaften urlbk und urlfw hinzugefügt werden, in denen (als relative URLs) die Links zu den zeitlich davor bzw. danach liegenden Daten (als JSON-Objekt) angegeben sind. Der Wert u bewirkt die Ergänzung der beiden Eigenschaften datebk und datefw, die im Format JJJJ-MM-TT die entsprechenden Datumsangaben enthalten. Default: Keine Hinzufügung.
jsonfunc Nur beim Format json: - Wird mit diesem Parameter ein Javascript-Funktionsname angegeben, dann wird anstatt eines JSON-Objekts ein Javascript zurückgegeben, das diese Funktion aufruft (sie sollte also vorher definiert sein) und als Parameter das JSON-Objekt übergibt (JSONP).

4. Beispiele

4.1 Jahreskalender eines bestimmten Jahres als Internetseite

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

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

4.2 Aktueller Jahreskalender als Internetseite mit Navigationszeilen oben und unten

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

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

4.3 Aktueller Monatskalender als Internetseite

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

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

4.4 Liturgische Termine des heutigen Tages als Internetseite

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

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

4.5 Liturgische Termine des morgigen Tages als Internetseite mit Navigationszeile oben

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

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

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

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

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

4.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://www.eucharistiefeier.de/lk/api.php?jahr=2025&monat=12&tag=13&format=html&info=wdtru&bahn=j&css=gelb

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

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

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

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

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

4.10 API-Zugriff über CSV-Datei 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.11 API-Zugriff über JSON-Datei per PHP

Ein andere Methoden ist die Nutzung des JSON-Formats. Hier ein Beispiel, wieder mit den Daten eines einzelnen Tages (Zeilen mit # davor sind Kommentare):

<?php
  
  # 1. Daten holen
  #    (dies setzt das Vertrauen voraus, dass www.eucharistiefeier.de keinen bösartigen Code liefert)
  $jsonurl='https://www.eucharistiefeier.de/lk/api.php?format=json&jahr=2018&monat=6&tag=27&kal=deutschland';
  $json = join("\n",file($jsonurl));
  
  # 2. Daten in ein PHP-Array umwandeln
  $J=json_decode($json, true);
  
  # 3. Zugriff auf einzelne Eigenschaften
  echo "<h3>Kalender: ".$J['Kalendername']."</h3>\n";
  # Schlüssel für $J sind: Kalendername, liturkalversion, Generator, Zelebrationen
  # Zelebrationen ist Bezeichner eines Arrays, das im Folgenden ausgewertet wird
  foreach($J["Zelebrationen"] as $ix => $zA) {
    # Array $zA enthält die Eigenschaften eines liturgischen Termins
    echo "<p>".$zA['Wtag'].", ".$zA['Datum'].": ".$zA['Tl']."</p>";
    # Ergibt etwas wie: Mittwoch, 2018-06-27: Cyrill, Bischof von Alexandrien, Kirchenlehrer (444)
    # Schlüssel für $zA sind: Wtag, Datum, Tl, Bem, L1, AP, L2, EV, Farbe, Datei, Grad, Rang
    # Werte von $zA['Rang'] sind: g = Gedenktag, G = gebotener Gedenktag, F = Fest, H = Hochfest
  }
  
?>

4.12 API-Zugriff per Javascript

Javascript bietet die Möglichkeit, sogar auf einem Server mit rein statischen Dateien, also ohne Script-Sprachen wie PHP, dynamische Seiten zu betreiben. Mittels des JSON-Formats kann auf die API zugegriffen werden. Hier ein Beispiel mit den Daten eines einzelnen Tages, aber dynamisch wechselnd zwischen verschiedenen Kalendern (Kommentare beginnen mit // ):

<script type="text/javascript">
  function zeige(kalender) {
    s=document.createElement("script");
    // Analog zur Angabe des Kalenders könnten im Folgenden auch andere Parameter dynamisch geändert werden.
    s.src="https://www.eucharistiefeier.de/lk/api.php?format=json&jahr=2017&monat=2&tag=25&"+
          "kal="+kalender+"&jsonfunc=zeigejson";
    // Mit der folgenden Methode appendChild wird das von der API gelieferte JSONP-Script eingebunden.
    // Dieses ruft die Funktion mit dem im URL angegebenen Namen zeigejson auf und übergibt diesem
    // das JSON-Objekt.
    document.body.appendChild(s);
  }
  function zeigejson(json) {
    // json ist hier das von der API ausgelieferte JSON-Objekt
    var txt="";
    txt+='<h3>Kalender: '+json['Kalendername']+'</h3>';
    var Z=json['Zelebrationen'];
    for (var ix in Z) {
      var zA=Z[ix]; // Array zA enthält die Eigenschaften eines liturgischen Termins
      txt+='<p>'+zA['Wtag']+', '+zA['Datum']+': '+zA['Tl']+'</p>'+"\n";
    }
    document.getElementById("demo").innerHTML=txt;
  }
</script>
<p>Kalender auswählen:
  <form name="f1">
    <input type="button" value="Salesianer Don Boscos" onclick="zeige('sdb')" /><br />
    <input type="button" value="München und Freising" onclick="zeige('muenchenfreising')" /><br />
    <input type="button" value="OSB Seckau" onclick="zeige('osbseckau')" />
  </form>
</p>
<div id="demo"></div>

Hier können Sie testen, wie der obige Code funktioniert: Demo

Auf der Startseite Liturgischer Kalender ist die Anzeige auf diese Weise eingebunden, erweitert durch Auswahlmöglichkeiten bei Datum und Teilkirche.

5. Eigene Daten einbeziehen (liturgische Kalender von Teilkirchen)

5.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://www.eucharistiefeier.de/lk/api.php?kal=koeln&nav=ou
http://www.eucharistiefeier.de/lk/api.php?kal=koeln&jahr=0&format=html&info=dtrfl&dup=z&bahn=j&nav=ou
http://www.eucharistiefeier.de/lk/api/lkou0000koeln.html
http://www.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.