The Church Calendar API provides access to calendar data for any day.

Swagger: Apart of this documentation for humans, there is also a Swagger documentation, which can be loaded in your favourite Swagger API browser or even used to generate client code.

Specify API Version and Language

API version must be specified at the beginning of each request path /api/:version/:lang Right now the API only has version 0 v0 and a few supported languages:

Full example: /api/v0/en

Due to a design flaw this API version handles temporale and sanctorale feast names independently. Temporale feast names are governed by language specified in request path. E.g. /api/v0/en/calendars/czech/... would return a mixture of Czech (for sanctorale) and English (for temporale) feast names. In order to have all Czech, it is necessary to specify Czech language. /api/v0/cs/calendars/czech/...

In the following examples the common beginning explained above is omitted for brevity.

Select Calendar to Query

The API offers several sanctorale calendars to choose from - e.g. General Roman Calendar in Latin and English. /calendars returns list of their identifiers.

[
  "default",
  "general-la",
  "general-en",
  "czech"
]

Fetches description of the selected calendar.

The description has two parts. system describes the calendar system (which is the same for the whole API), sanctorale describes the selected set of data of sanctorale feasts.

{
  "system": {
    "promulgated": 1969,
    "desc": "promulgated by motu proprio Mysterii Paschalis of Paul VI. (AAS 61 (1969), pp. 222-226)."
  },
  "sanctorale": {
    "title": "Calendarium Romanum Generale",
    "language": "la"
  }
}

Query the Calendar

Convenience shortcuts to get calendar entries for the current day and for the previous and next one.

By default date and time of the server's time zone is used. If you need to serve audience in different timezones or in a single timezone different from the server's one, use endpoint with explicitly specified date instead. Alternatively, if the client provides it's local time in the Date HTTP header, the server respects it. But specifying date in request path is definitely the preferred way.

{
  "date":"2015-06-27",
  "season":"ordinary",
  "season_week":12,
  "celebrations":[
    {"title":"","colour":"green","rank":"ferial","rank_num":3.13},
    {"title":"Saint Cyril of Alexandria, bishop and doctor","colour":"white","rank":"optional memorial","rank_num":3.12}
  ],
  "weekday":"saturday"
}

Useful shortcut: If you wish to query the default calendar, you may omit /calendars/default from the path. The API will redirect you with status 301 to the full path. E.g. /today redirects to /calendars/default/today This is especially useful when exploring the API manually through the address bar of your browser or curl on the command line.

Returns Day entry for the specified day.

Promulgation date as limit: The API refuses requests for dates with year being older than the year of promulgation of the implemented calendar system. You can find it by hitting the calendar description route.

Returns an array of Day entries for all days of the specified month

{"lectionary":"C","ferial_lectionary":2}

Returns the year's common "liturgical setup".

Civil vs. liturgical year: The way this endpoint works might not be obvious at the first glance. The problem is that the civil and Catholic liturgical year do not match. A liturgical year begins in November or December with the 1st Sunday of Advent. Thus /api/v0/en/2015 returns information concerning the liturgical year 2015-2016 and if you want to know which lectionary cycle is in use in June 2015, you have to call /api/v0/en/2014

Data Structures

The API mostly returns representations of liturgical days. On each liturgical day one or more celebrations occur.

Liturgical Day

{
  "date":"2015-06-27",
  "season":"ordinary",
  "season_week":12,
  "celebrations":[
    {"title":"","colour":"green","rank":"ferial","rank_num":3.13},
    {"title":"Saint Cyril of Alexandria, bishop and doctor","colour":"white","rank":"optional memorial","rank_num":3.12}
  ],
  "weekday":"saturday"
}

Celebration

{"title":"Saint Cyril of Alexandria, bishop and doctor","colour":"white","rank":"optional memorial","rank_num":3.12}