daily_psalms_api/README.md

Daily Psalms API

A JSON API for finding daily psalms, quran suras, and bible verses based on name and date inputs.

Overview

The Daily Psalms API provides endpoints to find meaningful religious texts based on a person's name and a specific date. It uses gematria (numerical values assigned to letters) to make these connections.

API Endpoints

GET /api/psalm

Returns a daily psalm based on name and date.

Parameters:

• name (optional): The name to use in calculation
• date: The date in YYYY-MM-DD format (default: current date)
• adjusted_sum: Whether to adjust the gematria sum (true/false, default: true)
• language: Language for translations (default: English)

Example Response:

{
  "input": {
    "name": "John",
    "date": "2025-06-07",
    "date_words": "June seventh two thousand twenty-five",
    "language": "English",
    "language_code": "en",
    "initial_gematria_sum": 1234
  },
  "els_result": {
    "text": "exampletext",
    "step": 42,
    "book": "Genesis",
    "gematria_sum": 567
  },
  "psalm": {
    "words": "Example psalm text",
    "chapter": 23,
    "verse": 1,
    "reference": "Psalms 23:1",
    "url": "https://www.biblegateway.com/passage/?search=Psalms+23&version=CJB"
  }
}

GET /api/sura

Returns a daily Quran sura based on name and date.

Parameters:

• name (optional): The name to use in calculation
• date: The date in YYYY-MM-DD format (default: current date)
• adjusted_sum: Whether to adjust the gematria sum (true/false, default: true)
• language: Language for translations (default: English)

GET /api/bible

Returns a daily Bible verse based on name and date.

Parameters:

• name (optional): The name to use in calculation
• date: The date in YYYY-MM-DD format (default: current date)
• adjusted_sum: Whether to adjust the gematria sum (true/false, default: true)
• language: Language for translations (default: English)

GET /api/all

Returns all results (psalm, sura, bible) in a single request.

Parameters:

• name (optional): The name to use in calculation
• date: The date in YYYY-MM-DD format (default: current date)
• adjusted_sum: Whether to adjust the gematria sum (true/false, default: true)
• language: Language for translations (default: English)

Example Response:

{
  "input": {
    "name": "John",
    "date": "2025-06-07",
    "date_words": "June seventh two thousand twenty-five",
    "language": "English",
    "language_code": "en",
    "initial_gematria_sum": 1234
  },
  "psalm": {
    "words": "Example psalm text",
    "chapter": 23,
    "verse": 1,
    "reference": "Psalms 23:1",
    "url": "https://www.biblegateway.com/passage/?search=Psalms+23&version=CJB",
    "els_result": {
      "text": "exampletext",
      "step": 42,
      "book": "Genesis",
      "gematria_sum": 567
    }
  },
  "sura": {
    "book": "Al-Fatiha",
    "chapter": 1,
    "verse": 1,
    "words": "Example sura text",
    "reference": "Quran 1:1",
    "url": "https://quran.com/1/1",
    "els_result": {
      "text": "exampletext",
      "step": 42,
      "gematria_sum": 789
    }
  },
  "bible": {
    "book_id": 66,
    "book_name": "Revelation",
    "chapter": 12,
    "num_verses": 21,
    "reference": "Revelation 12",
    "url": "https://www.biblegateway.com/passage/?search=Revelation+12&version=CJB",
    "els_result": {
      "text": "exampletext",
      "step": 42,
      "book": "Matthew",
      "gematria_sum": 890
    }
  }
}

GET /api/languages

Returns the list of available languages for translation.

Installation

1. Clone the repository
2. Install dependencies:

pip install -r requirements.txt

3. Make sure you have the necessary database files:
   • gematria.db
   • els_cache.db
   • abjad.db
   • bible.db

Usage

Run the API server:

python app.py

The server will start on port 5000 by default.

Structure

• app.py: Main API application
• gematria.py: Functions for calculating gematria values
• utils.py: Utility functions for date formatting and translation
• bible.py: Bible text processing functions
• torah.py: Torah text processing functions
• quran.py: Quran text processing functions
• texts/: Directory containing text files in JSON format

License

This project is open source and available under the MIT License.