Liturgy of the Hours data for developers
The daily ribbon guide as free, simple data files, one for every date.
Everything the daily guide works out is also published as small, plain data files, one per date. They are free, need no key or sign-up, and can be read from any website or app. A parish site can show today’s ribbons, a newsletter can print the week ahead, and an assistant can answer “what Psalter week is it?” from the source.
The files
| Address | What it holds |
|---|---|
/api/today.json | Today, rebuilt each night at about 4 a.m. Eastern. |
/api/2026-10-22.json | Any single date. Replace the date with the one you need, written year-month-day. |
/api/index.json | The range of dates currently published, about fifteen months ahead. |
/llms.txt | A plain-text summary of this site for AI tools. |
What each date contains
| Field | Meaning |
|---|---|
date, weekday | The date asked for, and its day of the week. |
season, week | Liturgical season and the week within it, e.g. Twenty-sixth Week in Ordinary Time. |
psalterWeek | I, II, III or IV: which week of the four-week Psalter to pray. |
liturgicalColor | green, violet, white, red or rose. |
celebration | The day’s celebration with its rank (Solemnity, Feast or Memorial), or null on a plain weekday. The rank is null on days the calendar prints without one, such as Ash Wednesday and the days of Holy Week. |
optionalMemorials, commemorations | Saints that may be kept, or that are reduced to a commemoration in Advent, Christmas and Lent. |
breviaryVolume | Which of the four volumes is in use. |
ribbonPlacements | Where every ribbon goes, for the first edition (5 ribbons) and the Second Edition from Word on Fire (7) and Ascension (8). Each ribbon has what it marks, whether it is used today, and a short note. |
page, attribution | A link to the matching calendar page, and the credit line to show. |
Using it
- Request the address for the date you need. The reply is standard JSON.
- Any website may read the files directly from the browser; cross-origin requests are allowed.
- Files are cached for an hour. Please fetch a date once and keep it, rather than on every page view.
- Dates follow the USCCB liturgical calendar for the United States. Other countries’ calendars differ on some days.
- The Second Edition layouts are provisional until the printed volumes ship in January 2027.
- The files give placements only. They do not contain the text of the Office.
Credit. The data is free to use in parish websites, apps and newsletters. Please show “Liturgy Ribbons (liturgyribbons.com)” with a link back. If you are building something larger, or would like a feed in another form, write to pray@liturgyribbons.com. We would be glad to hear what you make.