Reference / Calendar

Liturgical calendar

Query a date, a month or the whole year with the prayer book and preferences you choose.

Liturgical day

Returns the liturgical season and colour, the celebrations, the collects and the readings that belong to the date and preferences you sent.

GET/api/v1/calendar/today— today's date

GET/api/v1/calendar/:year/:month/:day— a specific date

/today uses the current date. Both endpoints require preferences[prayer_book_code]. For another date use /calendar/2026/03/25; the format is YYYY/MM/DD.

Response excerpt — 2026-03-25, loc_2015200 OK

{
  "date": "25/03/2026",
  "day_of_week": "Quarta-feira",
  "liturgical_season": "Quaresma",
  "liturgical_color": "branco",
  "liturgical_year": "A",
  "is_holy_day": true,
  "description": ["Anunciação de Nosso Senhor Jesus Cristo à Bem-Aventurada Virgem Maria"],
  "celebration": {
    "name": "Anunciação de Nosso Senhor Jesus Cristo à Bem-Aventurada Virgem Maria",
    "type": "principal_feast",
    "post_slug": "celebration-annunciation",
    "transferred": false
  },
  "readings": {
    "first_reading": {
      "reference": "Isaías 7:10-14",
      "book_name": "Isaías"
    },
    "psalm": {
      "reference": "Salmo 45"
    },
    "second_reading": {
      "reference": "Hebreus 10:4-10"
    },
    "gospel": {
      "reference": "Lucas 1:26-38"
    }
  }
}

The preferences parameter

Send the lectionary and Bible translations as a URL-encoded JSON object in the preferences parameter.

Key	Description
prayer_book_code	The book's code (e.g. loc_2015, loc_2019, loc_1662_en). It decides the liturgical rule and the collects.
bible_version	The Bible version's code. See /api/v1/bible_versions for the available options.
lectionary_variant	The BCP 1662's optional reading table: original_1662, revised_1871 or revised_1922. Use it only when the book declares this preference.
psalm_translation	The text of the Psalms: bible_version uses the chosen version; coverdale uses the 1662 Coverdale Psalter. Check the book's preferences.

Dynamic preferences: the values each book supports come from GET /api/v1/prayer_books/:prayer_book_code/preferences. For the English BCP 1662, use loc_1662_en and the variant you want inside preferences.

Field reference

Field	Description
date	The response date, formatted.
day_of_week	The name of the weekday, spelled out.
liturgical_season	The current liturgical season (e.g. Lent, Advent, Ordinary Time).
liturgical_color	The recommended colour of vestments and hangings (green, red, purple, white).
liturgical_year	The lectionary's annual cycle (A, B or C).
description	A list of texts describing the week or the specific day (e.g. "First Week of Lent").
celebration	An object with the details of the day's principal feast or saint.
collect	The list of prayers (collects) proper to the day.
readings	Structured biblical references for the day's lectionary.

The liturgical year at a glance

A set of year-scoped endpoints for questions like “when is Easter in 2027?” or “what are this year's principal feasts?”. All of them require the preferences parameter with prayer_book_code and are cached for a month.

GET/api/v1/calendar/:year/<endpoint>

1. /overview

Everything in one request: the liturgical cycle, the seasons, the movable dates and the celebrations. Made for generating a full annual calendar.

GET/api/v1/calendar/2026/overview?preferences={"prayer_book_code":"loc_2015"}

JSON response200 OK

{
  "year": 2026,
  "prayer_book": "loc_2015",
  "liturgical_year": "A",
  "seasons": [ /* liturgical seasons */ ],
  "key_dates": { /* movable dates */ },
  "celebrations": [ /* every celebration, in chronological order */ ],
  "celebrations_by_type": {
    "principal_feast": [ /* ... */ ],
    "major_holy_day":  [ /* ... */ ],
    "festival":        [ /* ... */ ],
    "lesser_feast":    [ /* ... */ ],
    "sunday":          [ /* ... */ ]
  }
}

2. /seasons

The six liturgical seasons of the year with their start and end dates. The Christmas season starts on 25 December of the previous year — that is expected.

GET/api/v1/calendar/2026/seasons?preferences={"prayer_book_code":"loc_2015"}

JSON response200 OK

[
  { "name": "Natal",        "slug": "season-christmas",     "start_date": "2025-12-25", "end_date": "2026-01-10" },
  { "name": "Epifania",     "slug": "season-epiphany",      "start_date": "2026-01-11", "end_date": "2026-02-17" },
  { "name": "Quaresma",     "slug": "season-lent",          "start_date": "2026-02-18", "end_date": "2026-04-04" },
  { "name": "Páscoa",       "slug": "season-easter",        "start_date": "2026-04-05", "end_date": "2026-05-24" },
  { "name": "Tempo Comum",  "slug": "season-ordinary-time", "start_date": "2026-05-25", "end_date": "2026-11-28" },
  { "name": "Advento",      "slug": "season-advent",        "start_date": "2026-11-29", "end_date": "2026-12-24" }
]

Field	Type	Description
name	string	The season's name
slug	string	Identifier used in link and post URLs
start_date	string (YYYY-MM-DD)	Start date (inclusive)
end_date	string (YYYY-MM-DD)	End date (inclusive)

3. /key_dates

The year's most important movable dates, all calculated from Easter by the Computus algorithm.

GET/api/v1/calendar/2026/key_dates?preferences={"prayer_book_code":"loc_2015"}

Response excerpt200 OK

{
  "ash_wednesday": {
    "date": "2026-02-18",
    "name": "Quarta-Feira de Cinzas",
    "post_slug": "celebration-ash-wednesday"
  },
  "palm_sunday": { "date": "2026-03-29" },
  "easter": {
    "date": "2026-04-05",
    "name": "Páscoa",
    "post_slug": "celebration-easter"
  },
  "first_sunday_of_advent": { "date": "2026-11-29" }
}

The name and post_slug fields are optional: if the prayer book has no celebration recorded for that date, the entry carries the date alone.

4. /celebrations

Every celebration of the year recorded in the prayer book. Supports filtering by type and grouping.

GET/api/v1/calendar/2026/celebrations?preferences={"prayer_book_code":"loc_2015"}

Parameter	Type	Values	Default
type	string	principal_feast · major_holy_day · festival · lesser_feast · commemoration	all
grouped	boolean	true · false	false

JSON response — chronological list (default)200 OK

[
  {
    "date": "2026-01-01",
    "name": "Santo Nome e Circuncisão de Nosso Senhor Jesus Cristo",
    "type": "principal_feast",
    "color": "branco",
    "post_slug": "celebration-holy-name-circumcision",
    "transferred": false
  }
  // ... every celebration of the year, in chronological order
]

JSON response — grouped (?grouped=true)200 OK

{
  "principal_feast": [ /* ... */ ],
  "major_holy_day":  [ /* ... */ ],
  "festival":        [ /* ... */ ],
  "lesser_feast":    [ /* ... */ ],
  "sunday":          [ /* ... */ ]
}
// types with no celebrations are omitted

Field	Type	Description
date	string (YYYY-MM-DD)	The observed date (it can differ from the original after a transfer)
name	string	The name as the prayer book gives it
type	string	The celebration's type (principal_feast, major_holy_day, festival, lesser_feast, commemoration)
color	string	Liturgical colour
post_slug	string \| null	Slug for linking to a post or article
transferred	boolean	true when the date was transferred by a liturgical conflict; date already carries the observed date

Errors

Status	Message
400	"Ano inválido: ..."
400	"O parâmetro preferences[prayer_book_code] é obrigatório"
400	"Tipo inválido. Valores aceitos: principal_feast, major_holy_day, festival, lesser_feast, commemoration"