Liturgical API

Get Liturgical information for a given date. This API server uses the Liturgical Calendar library.

This API can be self-hosted, or there is a free-to-use instance hosted at api.liturgical.uk

Usage

This is a read-only API without any authentication. Syntax is simple - simply supply the date in YYYY-MM-DD format.

https://api.liturgical.uk/<yyyy-mm-dd>

# curl https://api.liturgical.uk/2025-12-20
{
  "colour": "purple",
  "colourcode": "#664fa6",
  "date": "2025-12-20",
  "ember": 0,
  "name": "",
  "prec": 1,
  "season": "Advent",
  "season_url": "https://en.wikipedia.org/wiki/Advent",
  "week": "Advent 3",
  "weekno": 3
}

Run Locally

• 🔧 pip install -r src/app/requirements.txt
• 🚀 gunicorn src.app.app:app

Pull image

docker pull ghcr.io/liturgical-app/liturgical-api:latest

• Stable releases are built as image tags, e.g. 1.0.0
• The latest tag points to the latest stable release
• The edge tag is built from the latest commit to main

Run

A Helm chart is available for deploying on Kubernetes.

Issues

Issues should be logged against this project for problems with the API only. Problems relating to the calculations of dates, colours and the calendar of feasts should be logged against the Liturgical Calendar library.

PRs are welcome, but should pass the Pylint tests.