Catholic Readings API

A free, open-source REST API providing daily Catholic Mass readings, saints, and liturgical calendar data via GitHub Pages.

🙏 Mission

To provide the Catholic developer community with reliable, free access to liturgical data for building apps, websites, and tools that serve the faithful worldwide.

✨ Features

Daily Mass Readings - First Reading, Psalm, Second Reading (when applicable), Gospel
Saints & Feast Days - Complete calendar with quotes and biographical information
Saint Images - High-quality images from Wikipedia for memorial celebrations (2026+)
Liturgical Seasons - Ordinary Time, Advent, Christmas, Lent, Easter
USCCB Verification Links - Direct links to official USCCB readings
Wikipedia Integration - Research links for saints and feasts
JSON Format - Easy integration with any programming language
No Rate Limits - Completely free, powered by GitHub Pages
CORS Enabled - Access from web applications

🚀 Quick Start

Get Today's Readings

// Replace MM-DD with today's date (e.g., 09-07 for September 7)
fetch('https://cpbjr.github.io/catholic-readings-api/readings/2025/09-07.json')
  .then(response => response.json())
  .then(data => console.log(data));

Get Today's Celebration

fetch('https://cpbjr.github.io/catholic-readings-api/liturgical-calendar/2025/09-07.json')
  .then(response => response.json())
  .then(data => console.log(data));

📖 API Reference

Base URL

https://cpbjr.github.io/catholic-readings-api/

Endpoints

Readings

GET /readings/2025/{MM-DD}.json

Example Response:

{
  "date": "2025-09-07",
  "monthDay": "9/7",
  "season": "Ordinary Time",
  "readings": {
    "firstReading": "Wisdom 9:13-18b",
    "psalm": "Psalm 90:3-4, 5-6, 12-13, 14 and 17",
    "secondReading": "Philemon 9-10, 12-17",
    "gospel": "Luke 14:25-33"
  },
  "usccbLink": "https://bible.usccb.org/bible/readings/090725.cfm",
  "apiEndpoint": "https://cpbjr.github.io/catholic-readings-api/readings/2025/09-07.json"
}

Liturgical Calendar

GET /liturgical-calendar/2026/{MM-DD}.json

Example Response (Memorial with Saint Image):

{
  "date": "2026-01-31",
  "monthDay": "1/31",
  "season": "Ordinary Time",
  "celebration": {
    "name": "Saint John Bosco, Priest",
    "type": "MEMORIAL",
    "quote": "Run, jump, shout, but do not sin.",
    "description": "The 'Father and Teacher of Youth,' he founded the Salesians to care for and educate young people, especially the poor and abandoned.",
    "image": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/65/Don_Bosco_%40_Torino%2C_1880_%28original%29.jpg/500px-Don_Bosco_%40_Torino%2C_1880_%28original%29.jpg"
  },
  "apiEndpoint": "https://cpbjr.github.io/catholic-readings-api/liturgical-calendar/2026/01-31.json"
}

Note: Memorial celebrations (2026 onwards) include an image field with a direct URL to a saint image from Wikipedia Commons when available. Images are 500px wide thumbnails.

💡 Use Cases

Parish Websites

// Display daily readings on parish homepage
async function displayDailyReadings() {
    const today = new Date();
    const dateStr = `${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}`;
    
    const response = await fetch(`https://cpbjr.github.io/catholic-readings-api/readings/2025/${dateStr}.json`);
    const readings = await response.json();
    
    document.getElementById('first-reading').textContent = readings.readings.firstReading;
    document.getElementById('gospel').textContent = readings.readings.gospel;
}

Mobile Apps

// Swift example for iOS apps
struct CatholicReading: Codable {
    let date: String
    let season: String
    let readings: Readings
    let usccbLink: String
}

func fetchDailyReadings() {
    let url = URL(string: "https://cpbjr.github.io/catholic-readings-api/readings/2025/09-07.json")!
    URLSession.shared.dataTask(with: url) { data, response, error in
        // Handle response
    }.resume()
}

Automated Bulletins

# Python example for bulletin generation
import requests
from datetime import date

def get_sunday_readings():
    today = date.today()
    date_str = today.strftime("%m-%d")
    
    response = requests.get(f'https://cpbjr.github.io/catholic-readings-api/readings/2025/{date_str}.json')
    readings = response.json()
    
    return readings

🗓️ Data Coverage

Liturgical Year 2025

247 Total Entries - Complete coverage of major feasts and seasons
43 Daily Readings - From August through December 2025
204 Celebrations - Saints, Feasts, and Solemnities
All Liturgical Seasons - Ordinary Time, Advent, Christmas
Major Solemnities - Christmas, Epiphany, Annunciation, etc.

Liturgical Rankings Included

Solemnities - Christmas, Easter, Immaculate Conception
Feasts - Apostles, Evangelists, major saints
Memorials - Obligatory commemorations
Optional Memorials - Saints that may be celebrated

🛠️ Integration Examples

React Component

import { useState, useEffect } from 'react';

function DailyReadings() {
    const [readings, setReadings] = useState(null);
    
    useEffect(() => {
        const today = new Date();
        const dateStr = `${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}`;
        
        fetch(`https://cpbjr.github.io/catholic-readings-api/readings/2025/${dateStr}.json`)
            .then(res => res.json())
            .then(data => setReadings(data));
    }, []);
    
    if (!readings) return <div>Loading...</div>;
    
    return (
        <div>
            <h2>Daily Readings - {readings.date}</h2>
            <p><strong>First Reading:</strong> {readings.readings.firstReading}</p>
            <p><strong>Psalm:</strong> {readings.readings.psalm}</p>
            <p><strong>Gospel:</strong> {readings.readings.gospel}</p>
            <a href={readings.usccbLink} target="_blank">Verify on USCCB</a>
        </div>
    );
}

WordPress Plugin

<?php
function catholic_readings_shortcode() {
    $date = date('m-d');
    $url = "https://cpbjr.github.io/catholic-readings-api/readings/2025/{$date}.json";
    
    $response = wp_remote_get($url);
    $readings = json_decode(wp_remote_retrieve_body($response), true);
    
    return '<div class="daily-readings">
        <h3>Today\'s Readings</h3>
        <p><strong>First Reading:</strong> ' . $readings['readings']['firstReading'] . '</p>
        <p><strong>Gospel:</strong> ' . $readings['readings']['gospel'] . '</p>
    </div>';
}
add_shortcode('daily_readings', 'catholic_readings_shortcode');
?>

📅 Date Format

All endpoints use the format: MM-DD.json

Examples:

January 1: 01-01.json
March 17: 03-17.json (St. Patrick)
December 25: 12-25.json (Christmas)

🔗 Related Links

USCCB Official Readings: https://bible.usccb.org/
Vatican Liturgical Calendar: https://www.vatican.va/
Catholic Resource Library: https://catholic-resources.org/

🤝 Contributing

We welcome contributions from the Catholic developer community!

How to Contribute

Data Updates - Submit corrections or additions to readings/calendar
New Features - Suggest additional liturgical data (Liturgy of the Hours, etc.)
Bug Reports - Report incorrect dates, readings, or celebration information
Documentation - Improve examples, add new language samples

Liturgical Data Sources

United States Conference of Catholic Bishops (USCCB)
Roman Missal, Third Edition
Roman Martyrology
General Roman Calendar

Adding New Years

To add 2026 data:

Create readings/2026/ and liturgical-calendar/2026/ directories
Follow the existing JSON schema
Update README with new year coverage
Submit a pull request

📋 Roadmap

Future Enhancements

Liturgy of the Hours - Morning/Evening Prayer
Multiple Languages - Spanish, French, Portuguese
Liturgical Colors - Proper colors for each season
Propers - Collect prayers and readings for Mass
Mobile SDKs - Native iOS/Android libraries
RSS Feeds - Daily readings subscription
Webhook Support - Daily reading notifications

🏆 Recognition

Built with ❤️ for the Catholic community worldwide.

Special Thanks:

United States Conference of Catholic Bishops for official readings
Catholic developers who requested this resource
GitHub for free hosting via Pages

📞 Support

For Developers

Create an issue for bug reports or feature requests
Join discussions about Catholic tech development
Share your implementations and use cases

For Parishes & Organizations

This API is completely free for parish, school, and ministry use
No registration or API keys required
Suitable for commercial Catholic apps and websites

📜 License

MIT License - Free for all uses, including commercial applications.

See LICENSE file for full details.

"Go into all the world and preach the Gospel to every creature." - Mark 16:15

Built to serve the New Evangelization through technology.

Name		Name	Last commit message	Last commit date
.agent/Tasks		.agent/Tasks
generators		generators
liturgical-calendar		liturgical-calendar
node_modules		node_modules
readings		readings
.gitignore		.gitignore
DEPLOYMENT-GUIDE.md		DEPLOYMENT-GUIDE.md
GITHUB-METADATA.md		GITHUB-METADATA.md
LICENSE		LICENSE
README.md		README.md
START-HERE.md		START-HERE.md
deploy-to-github.sh		deploy-to-github.sh
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
setup-github-repo.sh		setup-github-repo.sh

Latest commit

History

Folders and files

Repository files navigation