<table class="validations"> <thead> <tr> <th colspan="2" scope="col" style="text-align: center; background-color: silver; color: black;">Code quality</th> <th scope="col" style="text-align: center; background-color: silver; color: black;">Translation status</th> <th scope="col" style="text-align: center; background-color: silver; color: black;">OpenAPI validation</th> </tr> </thead> <tbody> <tr> <th style="text-align: center; background-color: lightgray; color: black;" scope="row"> <a href="https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/tree/stable">stable branch</a> </th> <td style="text-align:center; background-color: whitesmoke;"> <a href="https://www.codefactor.io/repository/github/liturgical-calendar/liturgicalcalendarapi/overview/stable"> <img src="https://www.codefactor.io/repository/github/liturgical-calendar/liturgicalcalendarapi/badge/stable" title="CodeFactor" alt="CodeFactor" /> </a> </td> <td rowspan="2" style="text-align:center; background-color: whitesmoke;"> <a href="https://translate.johnromanodorazio.com/engage/liturgical-calendar/"> <img src="https://translate.johnromanodorazio.com/widgets/liturgical-calendar/-/287x66-white.png" alt="Translation status" /> </a> </td> <td style="text-align:center; background-color: whitesmoke;"> <a href="https://validator.swagger.io/validator?url=https://raw.githubusercontent.com/Liturgical-Calendar/LiturgicalCalendarAPI/stable/jsondata/schemas/openapi.json"> <img src="https://validator.swagger.io/validator?url=https://raw.githubusercontent.com/Liturgical-Calendar/LiturgicalCalendarAPI/stable/jsondata/schemas/openapi.json" alt="OpenAPI validation result" /> </a> </td> </tr> <tr> <th style="text-align: center; background-color: lightgray; color: black;" scope="row"> <a href="https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI/tree/development">dev branch</a> </th> <td style="text-align: center; background-color: whitesmoke;"> <a href="https://www.codefactor.io/repository/github/liturgical-calendar/liturgicalcalendarapi/overview/development"> <img src="https://www.codefactor.io/repository/github/liturgical-calendar/liturgicalcalendarapi/badge/development" title="CodeFactor" alt="CodeFactor" /> </a> </td> <td style="text-align: center; background-color: whitesmoke;"> <a href="https://validator.swagger.io/validator?url=https://raw.githubusercontent.com/Liturgical-Calendar/LiturgicalCalendarAPI/development/jsondata/schemas/openapi.json"> <img src="https://validator.swagger.io/validator?url=https://raw.githubusercontent.com/Liturgical-Calendar/LiturgicalCalendarAPI/development/jsondata/schemas/openapi.json" alt="OpenAPI validation result" /> </a> </td> </tr> </tbody> </table>

Liturgical Calendar

An API (PSR‑7/15/17 compliant) written in PHP that will generate the liturgical calendar for any given year, based on the General Roman Calendar, calculating the mobile festivities and the precedence of solemnities, feasts, memorials... Can also produce calendar data for nations, dioceses, or groups of dioceses. This calendar data can be served in various formats such as JSON, YAML, XML, or ICS. More information on the website.

OpenAPI documentation can be found here (kudos to @MichaelRShelton for generating the docs from the Swagger docker image).

The API is packaged as a composer library: run composer install to setup the autoload functionality.

Some characteristics of this API:

• The data is based on official sources, not copied from random internet sources. Sources used are the various editions of the Roman Missal in Latin, English, and Italian, Magisterial documents, and the Decrees of the Dicastery for Divine Worship and the Discipline of the Sacraments
  • Missale Romanum, Editio typica, 1970
  • Missale Romanum, Reimpressio emendata, 1971
  • Missale Romanum, Editio typica secunda, 1975
  • Missale Romanum, Editio typica tertia, 2002
  • Missale Romanum, Editio typica tertia emendata, 2008
  • Mysterii Paschalis, PAULUS PP. VI, 1969
  • Decrees of the Dicastery for Divine Worship
• The data is historically accurate, i.e. the liturgical calendar produced for the year 1979 will reflect the calendar as it was in that year, and not as it would be today (obviously future years will reflect the calendar as it is generated in the current year; as new decrees are issued by the Dicastery for Divine Worship and the Discipline of the Sacraments or new editions of the Roman Missal are published, the script will need to be updated to account for any new criteria)

Example applications

There are a few proof of concept example applications for usage of the API at LitCal Usage, which demonstrate generating an HTML representation of the Liturgical Calendar.

• The first example uses cURL in PHP to make a request to the endpoint and handle the results.
• The second example uses fetch in Javascript to make the request to the endpoint and handle the results.
• The third example makes use of the FullCalendar javascript framework to display the results from the fetch request in a nicely formatted calendar view.
• The fourth example is the same as the third except that it outputs the Messages first and the FullCalendar calendar view after.

All of these examples request JSON as the data exchange format generated by the endpoint. Any application could use the endpoint in a similar manner: an Android App, a plugin for a Desktop Publishing App...

Using the endpoint as a calendar URL for Calendar Apps

(See usage.php#calSubscription.)

• GOOGLE CALENDAR ON A DESKTOP COMPUTER: you can only add a calendar by URL using Google Calendar on a computer, I don't believe it is possible from smartphone / Android devices. At the bottom left corner of the screen, next to Other calendars, click on the + to add a new calendar and choose From URL. Paste in the URL of the endpoint with the desired parameters, (make sure you use ICS as value of the return_type parameter). And remember, if you omit the year parameter, it will use the current year. This should mean that as Google Calendar continues to poll the calendar URL (supposedly every 8 hours), on the turn of a new year new events should be created automatically for the new year. Once the calendar has been added from a computer, it should become available for the same gmail account on the Google Calendar app on a smartphone.
• CALENDAR APPS ON AN ANDROID DEVICE: after you have added a calendar by URL in your Google Calendar on a Desktop Computer, you should then find that calendar synchronized with your Google account, so the calendar should become available to any Android Calendar apps that have access to your Google account to synchronize calendars.
• IPHONE: go to Phone Settings -> Accounts -> Add account -> Other -> Add Calendar, and paste in the endpoint URL with the desired parameters, (make sure you use ICS as value of the return_type parameter). And remember, if you omit the year parameter, it will use the current year. This should mean that as the iPhone Calendar continues to poll the calendar URL, on the turn of a new year new events should be created automatically for the new year.
• MICROSOFT OUTLOOK (tested with Outlook 2013): at the bottom of the screen, switch from Email view to Calendar view. On the ribbon of the Home menu item, click on Open calendar -> From the internet. Paste the endpoint URL with the desired parameters, (make sure you use ICS as value of the return_type parameter). And remember, if you omit the year parameter, it will use the current year. On the following screen, check the checkbox along the lines of "Poll this calendar in the interval sug