# widebible

[![PyPI](https://img.shields.io/pypi/v/widebible)](https://pypi.org/project/widebible/)
[![Python](https://img.shields.io/pypi/pyversions/widebible)](https://pypi.org/project/widebible/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Python SDK for [WideBible](https://widebible.com) -- the complete Bible study platform with 66 books, 4 public domain translations (KJV, ASV, BBE, YLT), 3,000+ biblical people, 942 geocoded places, 432K cross-references, and structured study tools. Access verses, people, places, topics, glossary terms, timeline events, and reading plans through a clean Python API.

All data is drawn from [widebible.com](https://widebible.com), a scripture reference site covering the Old and New Testaments with cross-references, genealogies, geographical data, and curated reading plans. The REST API is free, requires no authentication, and returns JSON with CORS enabled.

> **Explore the Bible at [widebible.com](https://widebible.com)** -- [Books](https://widebible.com/) | [People](https://widebible.com/people/) | [Places](https://widebible.com/places/) | [Topics](https://widebible.com/topics/) | [Timeline](https://widebible.com/timeline/)

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You'll Find on WideBible](#what-youll-find-on-widebible)
  - [Bible Books & Translations](#bible-books--translations)
  - [Biblical People & Genealogies](#biblical-people--genealogies)
  - [Places & Geography](#places--geography)
  - [Cross-References & Parallel Passages](#cross-references--parallel-passages)
  - [Topics & Study Tools](#topics--study-tools)
- [API Endpoints](#api-endpoints)
- [Command-Line Interface](#command-line-interface)
- [API Reference](#api-reference)
- [Learn More About the Bible](#learn-more-about-the-bible)
- [Also Available](#also-available)
- [WideHoly Scripture Platform](#wideholy-scripture-platform)
- [License](#license)

## Install

```bash
# Core SDK (API client only)
pip install widebible

# With CLI
pip install "widebible[cli]"

# With MCP server for AI assistants
pip install "widebible[mcp]"

# Everything
pip install "widebible[all]"
```

## Quick Start

```python
from widebible import WideBible

# Initialize the client (no API key required)
client = WideBible()

# Get a Bible verse — John 3:16 in KJV translation
verse = client.get_verse("john", 3, 16)
print(verse)

# List all 66 books of the Bible with chapter and verse counts
books = client.list_books()
print(f"{books['count']} books")  # 66 books

# Search Bible verses by keyword
results = client.search("love", limit=5)
for v in results.get("results", []):
    print(f"{v['reference']}: {v['text'][:80]}...")

# Look up a biblical person — Moses, leader of the Exodus
moses = client.get_person("moses")
print(f"{moses['name']}: {moses['bio']}")

# Get a geocoded biblical place with coordinates
jerusalem = client.get_place("jerusalem")
print(f"{jerusalem['name']}: {jerusalem['latitude']}, {jerusalem['longitude']}")

# Always close when done, or use as context manager
client.close()
```

Using the context manager pattern:

```python
from widebible import WideBible

with WideBible() as client:
    # Get Genesis chapter list
    chapters = client.list_chapters(book="genesis")
    print(f"Genesis has {chapters['count']} chapters")

    # Explore cross-references from Genesis 1:1
    xrefs = client.list_cross_references(from_book="genesis", from_chapter=1, from_verse=1)
    print(f"{xrefs['count']} cross-references from Genesis 1:1")
```

## What You'll Find on WideBible

### Bible Books & Translations

The Bible consists of 66 books divided into the Old Testament (39 books, from Genesis through Malachi) and the New Testament (27 books, from Matthew through Revelation). These books span genres including law, history, poetry, prophecy, gospels, and epistles, written over roughly 1,500 years.

WideBible provides 4 public domain English translations, each with a different translation philosophy:

| Translation | Code | Year | Philosophy |
|-------------|------|------|------------|
| King James Version | `kjv` | 1611 | Formal equivalence, literary English |
| American Standard Version | `asv` | 1901 | Formal equivalence, updated language |
| Bible in Basic English | `bbe` | 1949 | Limited vocabulary (850 core words) |
| Young's Literal Translation | `ylt` | 1862 | Ultra-literal, preserves Hebrew/Greek word order |

Books are organized into 10 groups that reflect the literary and theological structure of the canon:

| Group | Testament | Books | Example |
|-------|-----------|-------|---------|
| Pentateuch | Old | 5 | Genesis, Exodus, Leviticus |
| Historical Books | Old | 12 | Joshua, Judges, Ruth, 1-2 Samuel |
| Wisdom Literature | Old | 5 | Job, Psalms, Proverbs, Ecclesiastes |
| Major Prophets | Old | 5 | Isaiah, Jeremiah, Ezekiel, Daniel |
| Minor Prophets | Old | 12 | Hosea, Joel, Amos, Malachi |
| Gospels | New | 4 | Matthew, Mark, Luke, John |
| Acts | New | 1 | Acts of the Apostles |
| Pauline Epistles | New | 13 | Romans, 1-2 Corinthians, Galatians |
| General Epistles | New | 8 | Hebrews, James, 1-2 Peter, 1-3 John |
| Apocalyptic | New | 1 | Revelation |

```python
# List all 66 books with chapter and verse counts
books = client.list_books()

# Get detailed information about a specific book
genesis = client.get_book("genesis")
print(f"{genesis['name']}: {genesis['chapter_count']} chapters, {genesis['verse_count']} verses")

# Retrieve a verse in a specific translation
verse = client.get_verse("john", 3, 16, translation="asv")
print(verse)

# Browse book groups to understand canon structure
groups = client.list_book_groups()
```

Learn more: [Bible Book Explorer](https://widebible.com/) | [Translation Comparison](https://widebible.com/translations/) | [Reading Plans](https://widebible.com/developers/)

### Biblical People & Genealogies

WideBible catalogs over 3,000 people mentioned in the Bible, from patriarchs and matriarchs through kings, prophets, and apostles. Each person entry includes biographical details, testament association, verse count, and Wikidata cross-references for further research.

The biblical narrative spans 10 major eras:

| Era | Period | Key Figures |
|-----|--------|-------------|
| Patriarchs | ~2000-1700 BC | Abraham, Isaac, Jacob, Joseph |
| Exodus | ~1446-1406 BC | Moses, Aaron, Miriam, Joshua |
| Judges | ~1375-1050 BC | Deborah, Gideon, Samson, Samuel |
| United Kingdom | ~1050-930 BC | Saul, David, Solomon |
| Divided Kingdom | ~930-586 BC | Elijah, Elisha, Isaiah, Jeremiah |
| Exile | ~586-538 BC | Daniel, Ezekiel, Esther |
| Return | ~538-400 BC | Ezra, Nehemiah, Zerubbabel |
| Intertestamental | ~400 BC-5 BC | Maccabees (referenced in NT context) |
| Gospel | ~5 BC-33 AD | Jesus, Mary, John the Baptist |
| Apostolic | ~33-100 AD | Peter, Paul, James, John |

```python
# Look up a biblical person by slug
moses = client.get_person("moses")
print(f"{moses['name']} — mentioned in {moses['verse_count']} verses")

# List all people, filter by testament
ot_people = client.list_people(testament="Old Testament")

# Browse people from a specific era
prophets = client.list_people(era="divided-kingdom")
```

Learn more: [Biblical People Directory](https://widebible.com/people/) | [Timeline of Biblical History](https://widebible.com/timeline/)

### Places & Geography

WideBible includes 942 geocoded biblical locations spanning the ancient Near East, from Egypt and Mesopotamia to the Greco-Roman world. Each place entry includes latitude/longitude coordinates, description, verse count, and Wikidata references.

| Region | Key Places | Significance |
|--------|------------|--------------|
| Galilee | Nazareth, Capernaum, Sea of Galilee | Jesus' childhood and early ministry |
| Judea | Jerusalem, Bethlehem, Jericho | Temple worship, birth of Jesus |
| Egypt | Goshen, Nile, Red Sea | Exodus narrative, Holy Family refuge |
| Mesopotamia | Babylon, Ur, Nineveh | Abraham's origin, Exile period |
| Asia Minor | Ephesus, Antioch, Galatia | Pauline missionary journeys |
| Rome | Rome, Puteoli | Center of the Roman Empire, Paul's trial |

```python
# Get a geocoded biblical place with coordinates
jerusalem = client.get_place("jerusalem")
print(f"{jerusalem['name']}: ({jerusalem['latitude']}, {jerusalem['longitude']})")

# List all places with optional filtering
places = client.list_places()
print(f"{places['count']} biblical places")
```

Learn more: [Biblical Places Map](https://widebible.com/places/) | [Glossary of Biblical Terms](https://widebible.com/glossary/)

### Cross-References & Parallel Passages

With 432,000+ cross-references, WideBible maps the internal connections between Bible passages. Cross-references reveal typological links (Old Testament events foreshadowing New Testament fulfillment), direct quotations, thematic parallels, and synoptic gospel parallels.

The most densely cross-referenced books include Psalms, Isaiah, and Matthew, reflecting the deep intertextual web of prophecy, fulfillment, and liturgical usage throughout the biblical canon.

```python
# Find cross-references from a specific verse
xrefs = client.list_cross_references(from_book="genesis", from_chapter=1, from_verse=1)
for ref in xrefs.get("results", [])[:5]:
    print(f"{ref['from_ref']} -> {ref['to_ref']}: {ref.get('explanation', '')}")

# Filter cross-references to a specific book
to_psalms = client.list_cross_references(to_book="psalms")
```

Learn more: [Cross-Reference Explorer](https://widebible.com/developers/) | [Topic Index](https://widebible.com/topics/)

### Topics & Study Tools

WideBible organizes verses into thematic topics for structured Bible study. Topics like Love, Faith, Prayer, Salvation, and Forgiveness each aggregate relevant verses across both testaments, providing a topical index for devotional reading and theological research.

Additional study tools include a glossary of biblical terms with Hebrew and Greek original words, a historical timeline with dated events, and curated reading plans for systematic Bible reading.

```python
# Browse all Bible study topics
topics = client.list_topics()

# Get verses grouped under a specific topic
love = client.get_topic("love")
print(f"'{love['name']}' topic: {love['verse_count']} verses")

# Look up a biblical term with Hebrew/Greek origins
covenant = client.get_glossary_term("covenant")
print(f"{covenant['term']}: {covenant['definition']}")
print(f"Hebrew: {covenant.get('hebrew_word', 'N/A')}")

# Explore the biblical timeline
eras = client.list_eras()
events = client.list_events(era="patriarchs")

# Browse curated reading plans
plans = client.list_reading_plans()
plan = client.get_reading_plan("bible-in-a-year")
print(f"{plan['name']}: {plan['duration_days']} days")
```

Learn more: [Topic Index](https://widebible.com/topics/) | [Biblical Glossary](https://widebible.com/glossary/) | [Reading Plans](https://widebible.com/developers/)

## API Endpoints

All endpoints are under `https://widebible.com/api/v1/bible/`. No authentication required. JSON responses with CORS enabled.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/books/` | List all 66 books |
| GET | `/books/{slug}/` | Book details (chapters, verse count) |
| GET | `/book-groups/` | List book groups (Pentateuch, Gospels, etc.) |
| GET | `/book-groups/{slug}/` | Book group details |
| GET | `/translations/` | List Bible translations |
| GET | `/translations/{code}/` | Translation details |
| GET | `/chapters/` | List chapters (filter: `book__slug`) |
| GET | `/verses/` | List/search verses (filter: `book__slug`, `chapter`, `verse`, `translation__code`; search: `search`) |
| GET | `/people/` | List biblical people |
| GET | `/people/{slug}/` | Person details |
| GET | `/places/` | List biblical places |
| GET | `/places/{slug}/` | Place details with coordinates |
| GET | `/topics/` | List study topics |
| GET | `/topics/{slug}/` | Topic details |
| GET | `/cross-references/` | List cross-references (filter: `from_book`, `from_chapter`, `from_verse`) |
| GET | `/glossary/` | List glossary terms |
| GET | `/glossary/{slug}/` | Glossary term details |
| GET | `/timeline-eras/` | List timeline eras |
| GET | `/timeline-events/` | List events (filter: `era__slug`) |
| GET | `/reading-plans/` | List reading plans |
| GET | `/reading-plans/{slug}/` | Reading plan with daily entries |

### Example

```bash
curl -s "https://widebible.com/api/v1/bible/books/genesis/"
```

```json
{
  "id": 1,
  "name": "Genesis",
  "slug": "genesis",
  "abbreviation": "Gen",
  "testament": "Old Testament",
  "order": 1,
  "chapter_count": 50,
  "verse_count": 1533,
  "description": "The book of beginnings — creation, the fall, the flood, and the patriarchs.",
  "url": "/books/genesis/"
}
```

Full API documentation at [widebible.com/developers/](https://widebible.com/developers/).
OpenAPI 3.1.0 spec: [widebible.com/api/schema/](https://widebible.com/api/schema/).

## Command-Line Interface

Install with `pip install "widebible[cli]"`:

```bash
# Get a specific verse by reference
widebible verse john.3.16
# John 3:16 (KJV)
# For God so loved the world, that he gave his only begotten Son...

# Get a verse in a different translation
widebible verse john.3.16 --translation asv

# Search verses by keyword
widebible search "love" --limit 5

# Get book information
widebible book genesis
# Genesis (Old Testament)
# Chapters: 50 | Verses: 1533

# Look up a biblical person
widebible person moses
# Moses (Old Testament)
# Mentioned in 847 verses

# Look up a biblical place
widebible place jerusalem
# Jerusalem
# Coordinates: 31.7683, 35.2137
# Mentioned in 816 verses
```

## API Reference

| Method | Arguments | Returns | Description |
|--------|-----------|---------|-------------|
| `list_books()` | `**params` | `dict` | List all 66 books |
| `get_book(slug)` | `slug: str` | `dict` | Book details |
| `list_book_groups()` | `**params` | `dict` | List book groups |
| `get_book_group(slug)` | `slug: str` | `dict` | Book group details |
| `list_translations()` | `**params` | `dict` | List translations |
| `get_translation(code)` | `code: str` | `dict` | Translation details |
| `list_chapters(book)` | `book: str \| None` | `dict` | List chapters |
| `get_verse(book, chapter, verse, translation)` | `book: str, chapter: int, verse: int, translation: str = "kjv"` | `dict` | Get a specific verse |
| `search(query, limit)` | `query: str, limit: int = 25` | `dict` | Search verses |
| `list_people()` | `**params` | `dict` | List biblical people |
| `get_person(slug)` | `slug: str` | `dict` | Person details |
| `list_places()` | `**params` | `dict` | List biblical places |
| `get_place(slug)` | `slug: str` | `dict` | Place details with coordinates |
| `list_topics()` | `**params` | `dict` | List study topics |
| `get_topic(slug)` | `slug: str` | `dict` | Topic details |
| `list_cross_references()` | `**params` | `dict` | List cross-references |
| `list_glossary()` | `**params` | `dict` | List glossary terms |
| `get_glossary_term(slug)` | `slug: str` | `dict` | Glossary term definition |
| `list_eras()` | `**params` | `dict` | List timeline eras |
| `list_events(era)` | `era: str \| None` | `dict` | List timeline events |
| `list_reading_plans()` | `**params` | `dict` | List reading plans |
| `get_reading_plan(slug)` | `slug: str` | `dict` | Reading plan with entries |

## Learn More About the Bible

- **Scripture**: [Bible Books](https://widebible.com/) | [Bible Translations](https://widebible.com/translations/) | [Reading Plans](https://widebible.com/developers/)
- **Reference**: [Biblical People](https://widebible.com/people/) | [Biblical Places](https://widebible.com/places/) | [Cross-References](https://widebible.com/developers/)
- **Study**: [Topic Index](https://widebible.com/topics/) | [Biblical Glossary](https://widebible.com/glossary/) | [Timeline](https://widebible.com/timeline/)
- **Tools**: [Verse Search](https://widebible.com/) | [Developer Docs](https://widebible.com/developers/)
- **API**: [REST API Documentation](https://widebible.com/developers/) | [OpenAPI Spec](https://widebible.com/api/schema/)

## Also Available

| Platform | Package | Install |
|----------|---------|---------|
| **PyPI** | [widebible](https://pypi.org/project/widebible/) | `pip install widebible` |
| **npm** | [widebible](https://www.npmjs.com/package/widebible) | `npm install widebible` |
| **Go** | [widebible-go](https://pkg.go.dev/github.com/dobestan/widebible-go) | `go get github.com/dobestan/widebible-go` |
| **Rust** | [widebible](https://crates.io/crates/widebible) | `cargo add widebible` |
| **Ruby** | [widebible](https://rubygems.org/gems/widebible) | `gem install widebible` |
| **MCP** | widebible-mcp | `uvx --from "widebible[mcp]" python -m widebible.mcp_server` |

## WideHoly Scripture Platform

Part of the [WideHoly](https://wideholy.com) multi-religion scripture platform.

| Site | Domain | Focus |
|------|--------|-------|
| **WideBible** | [widebible.com](https://widebible.com) | **66 books, 4 translations (KJV, ASV, BBE, YLT), 3,000+ people, 942 places, 432K cross-references** |
| WideQuran | [widequran.com](https://widequran.com) | 114 surahs, hadith collections, tafsir commentary, Quranic figures |
| WideTorah | [widetorah.com](https://widetorah.com) | Tanakh, 54 parashot, Talmud tractates, Rashi commentary |
| WideGita | [widegita.com](https://widegita.com) | 18 Gita chapters, Upanishads, Yoga Sutras, Hindu deities |
| WideSutra | [widesutra.com](https://widesutra.com) | Tipitaka, Mahayana sutras, Buddhist figures, core concepts |
| WideHoly | [wideholy.com](https://wideholy.com) | Cross-religion search, verse comparison, religious calendar |

## License

MIT
