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:**
```json
{
  "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:**
```json
{
  "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.