# widebible
[](https://crates.io/crates/widebible)
[](https://docs.rs/widebible)
[](https://opensource.org/licenses/MIT)
Async Rust SDK for the [WideBible](https://widebible.com) API. Access all 66 books of the Bible, verses across multiple translations (KJV, ASV, BBE, YLT), biblical people, places, topics, cross-references, glossary terms, timeline events, and reading plans.
Built on [widebible.com](https://widebible.com) -- a comprehensive Bible encyclopedia with full-text search, cross-references between Old and New Testament passages, and study tools for scholars and developers.
## Install
```toml
[dependencies]
widebible = "0.1"
tokio = { version = "1", features = ["full"] }
```
Or via the command line:
```bash
cargo add widebible tokio --features tokio/full
```
## Quick Start
```rust
use widebible::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new();
// List all 66 books of the Bible
let books = client.list_books().await?;
println!("Total books: {:?}", books.count);
// Get a specific verse -- John 3:16 in KJV
let verse = client.get_verse("john", 3, 16, "kjv").await?;
for v in &verse.results {
println!("{}: {}", v.reference.as_deref().unwrap_or(""), v.text.as_deref().unwrap_or(""));
}
// Search across all Bible verses
let results = client.search("love").await?;
println!("Found {:?} results for 'love'", results.count);
Ok(())
}
```
## What You Can Do
### Books and Translations
The Bible contains 66 books across two testaments. WideBible organizes them into book groups -- Pentateuch (Genesis through Deuteronomy), Historical Books, Wisdom Literature, Major Prophets, Minor Prophets, Gospels, Pauline Epistles, General Epistles, and Revelation.
Four English translations are available: King James Version (KJV, 1611), American Standard Version (ASV, 1901), Bible in Basic English (BBE, 1949), and Young's Literal Translation (YLT, 1862).
```rust
// List book groups (Pentateuch, Gospels, etc.)
let groups = client.list_book_groups().await?;
// Get details for a specific book
let genesis = client.get_book("genesis").await?;
// List available translations
let translations = client.list_translations().await?;
```
### Verses and Search
Every verse is indexed for full-text search. Retrieve individual verses by book, chapter, and verse number, or search across the entire Bible by keyword.
```rust
// Get Genesis 1:1 in KJV
let verse = client.get_verse("genesis", 1, 1, "kjv").await?;
// Search for verses about faith
let results = client.search("faith").await?;
```
### People and Places
WideBible catalogues biblical people -- prophets, kings, apostles, judges -- and places with geocoded coordinates. Explore figures like Abraham, Moses, David, and Paul, or locations like Jerusalem, Bethlehem, and Mount Sinai.
```rust
// List all biblical people
let people = client.list_people().await?;
// Get details for a specific person
let moses = client.get_person("moses").await?;
// List biblical places
let places = client.list_places().await?;
```
### Topics and Cross-References
Thematic verse collections group passages by topic -- love, faith, prayer, salvation, creation, wisdom, and more. Cross-references connect related passages across Old and New Testaments.
```rust
// List thematic topics
let topics = client.list_topics().await?;
// Get verses for a specific topic
let love = client.get_topic("love").await?;
// List cross-references
let xrefs = client.list_cross_references().await?;
```
### Glossary and Timeline
The glossary defines Hebrew and Greek biblical terms with transliterations and definitions. The timeline places events in historical context across eras from the Patriarchs through the Early Church.
```rust
// List glossary terms
let glossary = client.list_glossary().await?;
// Get a specific term
let term = client.get_glossary_term("agape").await?;
// List timeline eras
let eras = client.list_eras().await?;
```
### Reading Plans
Structured Bible reading plans guide readers through Scripture over defined periods -- chronological reading, thematic studies, and book-by-book plans.
```rust
let plans = client.list_reading_plans().await?;
let plan = client.get_reading_plan("chronological").await?;
```
## API Methods
| `list_books()` | List all 66 books of the Bible |
| `get_book(slug)` | Get book details by slug |
| `list_book_groups()` | List book groups (Pentateuch, Gospels, etc.) |
| `get_book_group(slug)` | Get book group details |
| `list_translations()` | List available translations (KJV, ASV, BBE, YLT) |
| `get_translation(code)` | Get translation details |
| `get_verse(book, chapter, verse, translation)` | Get a specific verse |
| `search(query)` | Search Bible verses by keyword |
| `list_people()` | List biblical people |
| `get_person(slug)` | Get person details |
| `list_places()` | List biblical places |
| `get_place(slug)` | Get place details |
| `list_topics()` | List thematic verse collections |
| `get_topic(slug)` | Get topic details |
| `list_cross_references()` | List cross-references |
| `list_glossary()` | List glossary terms |
| `get_glossary_term(slug)` | Get glossary term definition |
| `list_eras()` | List timeline eras |
| `list_events()` | List timeline events |
| `list_reading_plans()` | List reading plans |
| `get_reading_plan(slug)` | Get reading plan details |
All methods are async and return `Result<T, WideBibleError>`.
## Custom Base URL
```rust
let client = Client::with_base_url("http://localhost:8000/api/v1/bible");
```
## Error Handling
```rust
use widebible::{Client, WideBibleError};
let client = Client::new();
match client.get_book("nonexistent").await {
Ok(book) => println!("Found: {:?}", book.name),
Err(WideBibleError::Api { status, body }) => {
eprintln!("API error {}: {}", status, body);
}
Err(WideBibleError::Http(e)) => {
eprintln!("Network error: {}", e);
}
}
```
## WideHoly Scripture Platform
Part of the [WideHoly](https://wideholy.com) multi-religion scripture platform.
| **WideBible** | [widebible.com](https://widebible.com) | **66 books, 4 translations, cross-references, study tools** |
| WideQuran | [widequran.com](https://widequran.com) | 114 surahs, hadith, tafsir, Quranic people |
| WideTorah | [widetorah.com](https://widetorah.com) | Tanakh, Talmud, Mishnah, Rashi, parashot |
| WideGita | [widegita.com](https://widegita.com) | Bhagavad Gita, Upanishads, Yoga Sutras, deities |
| WideSutra | [widesutra.com](https://widesutra.com) | Tipitaka, Pali Canon, Buddhist concepts |
| WideHoly | [wideholy.com](https://wideholy.com) | Cross-religion hub, comparison, calendar |
## Also Available
| **Rust** | [widebible](https://crates.io/crates/widebible) | `cargo add widebible` |
| Python | [widebible](https://pypi.org/project/widebible/) | `pip install widebible` |
| TypeScript | [widebible](https://www.npmjs.com/package/widebible) | `npm install widebible` |
## Learn More About the Bible
- **Scripture**: [Books](https://widebible.com/) · [Translations](https://widebible.com/translations/)
- **Reference**: [People](https://widebible.com/people/) · [Places](https://widebible.com/places/) · [Topics](https://widebible.com/topics/)
- **Study**: [Glossary](https://widebible.com/glossary/) · [Timeline](https://widebible.com/timeline/)
- **Tools**: [Search](https://widebible.com/) · [Developer Docs](https://widebible.com/developers/)
- **API**: [Developer Docs](https://widebible.com/developers/) · [OpenAPI Spec](https://widebible.com/api/schema/)
## License
MIT