The Church Calendar API provides access to calendar data for any day. You may explore the API by following the links bellow and experimenting with the URIs.

Specify API Version

API version must be specified at the beginning of each request path /api/:version/:lang - right now the API only has version 0 and language English: /api/v0/en

In the following examples this common beginning is omitted.

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. Don't use these endpoints if you need to serve audience in different timezones or in a single timezone different from the API server's one.

{
  "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"
}

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 in the command line.

Returns Day entry for the specified day.

Plese note: 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".

Important: 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}