API Reference

API Reference

Authentication

Read-only endpoints (/calendar, /calendars, /events, /easter, /schemas) are publicly accessible without authentication. Write endpoints (PUT/PATCH/DELETE on /data, /tests, /temporale) require authentication via an OIDC token or API key. See API keys for how to register as a developer and obtain a key, or the OpenAPI documentation for full endpoint details.

Routes

The API uses path-based routing. The primary endpoint for generating a liturgical calendar is /calendar, with optional path segments for calendar type, calendar ID, and year:

• /calendar — General Roman Calendar for the current year
• /calendar/{year} — General Roman Calendar for a specific year
• /calendar/nation/{calendar_id} — National calendar for the current year
• /calendar/nation/{calendar_id}/{year} — National calendar for a specific year
• /calendar/diocese/{calendar_id} — Diocesan calendar for the current year
• /calendar/diocese/{calendar_id}/{year} — Diocesan calendar for a specific year

Additional endpoints include:

• /calendars — Discovery endpoint: lists all available calendars, supported locales, and request parameters
• /events — Returns the full catalog of possible liturgical events
• /easter — Easter date calculations
• /data — Calendar definition source data (national, diocesan, wider region)
• /missals — Roman Missal metadata
• /decrees — Dicastery decree information
• /schemas — JSON schema definitions
• /tests — Liturgical event test definitions

The calendar endpoints support both GET and POST requests. For POST requests, the body can be JSON encoded (application/json), YAML encoded (application/yaml), or form encoded (application/x-www-form-urlencoded).

Calendar request parameters

While the calendar type, ID, and year are specified in the URL path, additional parameters can be passed as query parameters (GET) or in the request body (POST):

• locale: Sets the language for the calendar response. The locale can also be set via the Accept-Language header, which is the preferred method. The list of supported locales for each calendar can be found in the /calendars discovery endpoint response.
• epiphany: JAN6 or SUNDAY_JAN2_JAN8 (default: JAN6). Whether Epiphany falls on January 6th or on the Sunday between January 2nd and January 8th. Each Conference of Bishops can opt to celebrate on the Sunday.
• ascension: THURSDAY or SUNDAY (default: SUNDAY). Whether the Ascension falls on a Thursday or on a Sunday. Each Conference of Bishops can opt to celebrate on Sunday for pastoral reasons.
• corpus_christi: THURSDAY or SUNDAY (default: SUNDAY). Whether Corpus Christi falls on a Thursday or on a Sunday. Each Conference of Bishops can opt to celebrate on Sunday for pastoral reasons.
• eternal_high_priest: true or false (default: false). Whether to include the feast of Jesus Christ, Eternal High Priest in the calendar.
• year_type: CIVIL or LITURGICAL (default: LITURGICAL). The liturgical year begins with the first Sunday of Advent and ends with Saturday of the 34th week of Ordinary Time. The civil year returns results from January 1st to December 31st.
• return_type: JSON, XML, YAML, or ICS (default: JSON). The response format can also be set via the Accept header (application/json, application/xml, application/yaml, or text/calendar), which is the preferred method.

When a national or diocesan calendar is requested (via the URL path), the epiphany, ascension, and corpus_christi parameters are automatically set to the values defined for that calendar. The locale is set to the default locale for the calendar, unless overridden by the Accept-Language header.

The year parameter (range 1970-9999, default: current year) is specified as a path segment rather than a query parameter.

Parameter names are lowercase. Enum parameter values are uppercase.

Structure of the responses

The JSON response from the /calendar endpoint contains four top-level properties: litcal, settings, metadata, and messages.

litcal

An array of objects representing the liturgical events generated for the requested calendar. Each event object contains the following properties:

Always present:

Property	Type	Description
event_key	string	Unique identifier for the event (e.g., "MotherGod")
event_idx	int	Generation order index, useful for ordering events on the same day
name	string	Localized display name of the event
date	string	RFC 3339 datetime (e.g., "2025-01-01T00:00:00+00:00")
year	int	Civil year
month	int	Month number (1-12)
day	int	Day of month (1-31)
month_short	string	Localized abbreviated month name
month_long	string	Localized full month name
day_of_the_week_iso8601	int	Day of week (1=Monday, 7=Sunday)
day_of_the_week_short	string	Localized abbreviated weekday name
day_of_the_week_long	string	Localized full weekday name
color	array<string>	Liturgical colors (e.g., ["white"] or ["red","white"])
color_lcl	array<string>	Localized color names
type	string	"fixed" or "mobile"
grade	int	Numeric grade (0-7), used for precedence calculations
grade_lcl	string	Localized grade name (e.g., "Solemnity")
grade_abbr	string	Localized abbreviated grade name
grade_display	string or null	Override display grade when it differs from the numeric grade
common	array<string>	Liturgical commons (e.g., ["Pastores:For a Bishop"])
common_lcl	string	Localized commons text ready for display
readings	object	Lectionary readings for the event

Conditional (present only when applicable):

Property	Type	Description
liturgical_year	string	Lectionary cycle (e.g., "Year A", "Year I")
liturgical_season	string	Season enum (e.g., "ADVENT", "LENT", "ORDINARY_TIME")
liturgical_season_lcl	string	Localized season name
psalter_week	int	Psalter week (1-4)
has_vigil_mass	bool	Whether a vigil Mass exists on the preceding day
has_vesper_i	bool	Whether first vespers should be celebrated on the preceding day
has_vesper_ii	bool	Whether second vespers should be celebrated
is_vigil_mass	bool	Whether this event itself is a vigil Mass (always true when present)
is_vigil_for	string	The event_key of the event this vigil precedes
holy_day_of_obligation	bool	Whether this is a holy day of obligation (only present when true)

Notes on specific properties:

• date: Uses RFC 3339 format. The time component is always 00:00:00+00:00 (UTC). In JavaScript, new Date("2025-01-01T00:00:00+00:00") parses this natively. When formatting for display, use timeZone: 'UTC' with Intl.DateTimeFormat to avoid off-by-one errors from timezone offsets.

• color: An array of lowercase English color strings: "green", "purple", "white", "red", or "rose". Multiple colors indicate that a choice is available (e.g., commons with different liturgical colors). The color_lcl array provides the same colors translated to the requested locale.

• grade: Numeric values map to liturgical grades: 0=weekday, 1=commemoration, 2=optional memorial, 3=memorial, 4=feast, 5=feast of the Lord, 6=solemnity, 7=higher precedence than a solemnity. Some events have a logical grade that differs from their display grade (e.g., "All Souls Day" has grade 6 but displays as "Commemoration"). Use grade_display when it is non-null; otherwise fall back to grade_lcl or grade_abbr.

• common: An array of strings. Each string identifies a liturgical common, optionally with a specific category separated by a colon (e.g., "Pastores:For a Bishop"). When the celebration has Proper texts, the array contains ["Proper"]. The common_lcl property provides a pre-formatted localized string ready for display.

settings

An object reflecting the settings that were used to generate the calendar:

{
  "year": 2025,
  "epiphany": "JAN6",
  "ascension": "SUNDAY",
  "corpus_christi": "SUNDAY",
  "eternal_high_priest": false,
  "locale": "la",
  "return_type": "json",
  "year_type": "LITURGICAL"
}

When a national or diocesan calendar was requested, additional properties national_calendar and/or diocesan_calendar are included.

metadata

Provides context about how the calendar was generated:

Property	Type	Description
version	string	API version
timestamp	int	Unix timestamp when the response was generated
date_time	string	RFC 3339 datetime when the response was generated
request_headers	object	Relevant request headers received by the API
solemnities	array<string>	Event keys of all solemnities in the calendar
solemnities_lord_bvm	array<string>	Event keys of solemnities of the Lord and the BVM
feasts_lord	array<string>	Event keys of feasts of the Lord
feasts	array<string>	Event keys of all feasts
memorials	array<string>	Event keys of all memorials
suppressed_events	array<string>	Event keys of events suppressed by higher celebrations
reinstated_events	array<string>	Event keys of events that were reinstated

When a diocesan calendar is requested, the metadata also includes a diocese_name property.

messages

An array of strings describing the significant operations performed during calendar generation, such as event suppressions, date movements, rank reductions, and decree applications. Useful for understanding how or why the calculations were done.

---

For Developers: API keys Next → | Home