# widequran
[](https://crates.io/crates/widequran)
[](https://docs.rs/widequran)
[](https://opensource.org/licenses/MIT)
Async Rust SDK for the [WideQuran](https://widequran.com) API. Access all 114 surahs, 6,236 ayahs across multiple translations, hadith collections (Bukhari, Muslim, and more), tafsir commentaries (Ibn Kathir, Jalalayn), Quranic people and prophets, topics, and Islamic glossary terms.
Built on [widequran.com](https://widequran.com) -- a comprehensive Quran encyclopedia with full-text search, Arabic text with transliteration, and scholarly commentary for students and developers.
## Install
```toml
[dependencies]
widequran = "0.1"
tokio = { version = "1", features = ["full"] }
```
Or via the command line:
```bash
cargo add widequran tokio --features tokio/full
```
## Quick Start
```rust
use widequran::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::new();
// List all 114 surahs
let surahs = client.list_surahs().await?;
println!("Total surahs: {:?}", surahs.count);
// Get surah Al-Fatihah
let fatihah = client.get_surah("al-fatihah").await?;
println!("Surah: {:?}", fatihah.name);
// Search ayahs across the Quran
let results = client.search("mercy").await?;
println!("Found {:?} results for 'mercy'", results.count);
Ok(())
}
```
## What You Can Do
### Surahs and Ayahs
The Quran contains 114 surahs (chapters) with 6,236 ayahs (verses). Surahs are classified as Meccan (revealed in Mecca) or Medinan (revealed in Medina). Each ayah is available in Arabic script with multiple English translations.
```rust
// List all surahs
let surahs = client.list_surahs().await?;
// Get a specific surah
let baqarah = client.get_surah("al-baqarah").await?;
// Get a specific ayah by ID
let ayah = client.get_ayah(1).await?;
// Search ayahs
let results = client.search("paradise").await?;
```
### Juz and Hizb Divisions
The Quran is divided into 30 juz (parts) for structured reading, each further divided into hizb (half-juz) markers. These divisions support the tradition of completing the Quran during Ramadan.
```rust
// List all 30 juz
let juz = client.list_juz().await?;
// Get a specific juz
let juz_1 = client.get_juz(1).await?;
// List hizb markers
let hizbs = client.list_hizbs().await?;
```
### Tafsir (Commentary)
Classical and modern tafsir commentaries provide scholarly interpretation. Available collections include Ibn Kathir, Jalalayn, and others, offering verse-by-verse exegesis.
```rust
// List tafsir collections
let tafsirs = client.list_tafsirs().await?;
// Get a specific tafsir
let ibn_kathir = client.get_tafsir("ibn-kathir").await?;
// List tafsir entries
let entries = client.list_tafsir_entries().await?;
```
### Hadith Collections
Hadith (prophetic traditions) from the six canonical collections -- Sahih al-Bukhari, Sahih Muslim, Sunan Abu Dawud, Sunan al-Tirmidhi, Sunan al-Nasa'i, and Sunan Ibn Majah -- with grading (sahih, hasan, da'if).
```rust
// List hadith collections
let collections = client.list_hadith_collections().await?;
// Get hadiths from Bukhari
let hadiths = client.list_hadiths(Some("bukhari")).await?;
// Search hadiths
let results = client.search_hadith("prayer").await?;
```
### People and Prophets
The Quran mentions 25 prophets by name, from Adam to Muhammad. WideQuran catalogues each prophet with their Arabic name, story references, and the surahs in which they appear.
| Adam | آدم | First human, first prophet | Al-Baqarah, Al-A'raf |
| Ibrahim (Abraham) | إبراهيم | Father of monotheism | Ibrahim, Al-Baqarah |
| Musa (Moses) | موسى | Liberator, Torah recipient | Ta-Ha, Al-Qasas |
| Isa (Jesus) | عيسى | Messiah, Word of God | Al-Imran, Maryam |
| Muhammad | محمد | Final prophet, Quran recipient | Muhammad, Al-Fath |
```rust
let people = client.list_people().await?;
let ibrahim = client.get_person("ibrahim").await?;
```
### Topics and Glossary
Topics group ayahs thematically -- mercy, justice, prayer, charity, patience, and more. The glossary defines Arabic Islamic terms with transliterations, covering words like taqwa (God-consciousness), iman (faith), ihsan (excellence), salah (prayer), and zakat (charity).
```rust
let topics = client.list_topics().await?;
let glossary = client.list_glossary().await?;
let term = client.get_glossary_term("taqwa").await?;
```
## API Methods
| `list_surahs()` | List all 114 surahs |
| `get_surah(slug)` | Get surah details |
| `list_translations()` | List available translations |
| `get_translation(code)` | Get translation details |
| `list_ayahs(surah)` | List ayahs, optionally filtered by surah |
| `get_ayah(id)` | Get a specific ayah |
| `search(query)` | Search ayahs by keyword |
| `list_juz()` | List all 30 juz |
| `get_juz(number)` | Get juz details |
| `list_hizbs()` | List hizb markers |
| `get_hizb(number)` | Get hizb details |
| `list_tafsirs()` | List tafsir collections |
| `get_tafsir(slug)` | Get tafsir details |
| `list_tafsir_entries()` | List tafsir entries |
| `get_tafsir_entry(id)` | Get a specific tafsir entry |
| `list_hadith_collections()` | List hadith collections |
| `get_hadith_collection(slug)` | Get collection details |
| `list_hadiths(collection)` | List hadiths |
| `get_hadith(id)` | Get a specific hadith |
| `search_hadith(query)` | Search hadiths |
| `list_people()` | List Quranic people |
| `get_person(slug)` | Get person details |
| `list_topics()` | List Quranic topics |
| `get_topic(slug)` | Get topic details |
| `list_glossary()` | List Islamic glossary terms |
| `get_glossary_term(slug)` | Get glossary term |
All methods are async and return `Result<T, WideQuranError>`.
## Custom Base URL
```rust
let client = Client::with_base_url("http://localhost:8000/api/v1/quran");
```
## 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** | [widequran](https://crates.io/crates/widequran) | `cargo add widequran` |
| Python | [widequran](https://pypi.org/project/widequran/) | `pip install widequran` |
| TypeScript | [widequran](https://www.npmjs.com/package/widequran) | `npm install widequran` |
## Learn More About the Quran
- **Scripture**: [Surahs](https://widequran.com/) · [Translations](https://widequran.com/translations/)
- **Reference**: [People](https://widequran.com/people/) · [Topics](https://widequran.com/topics/) · [Glossary](https://widequran.com/glossary/)
- **Study**: [Tafsir](https://widequran.com/tafsir/) · [Hadith Collections](https://widequran.com/hadith/) · [Juz Divisions](https://widequran.com/juz/)
- **Tools**: [Search](https://widequran.com/) · [Developer Docs](https://widequran.com/developers/)
- **API**: [Developer Docs](https://widequran.com/developers/) · [OpenAPI Spec](https://widequran.com/api/schema/)
## Embed Widget
Embed [WideQuran](https://widequran.com) widgets on any website with [widequran-embed](https://widget.widequran.com):
```html
<script src="https://cdn.jsdelivr.net/npm/widequran-embed@1/dist/embed.min.js"></script>
<div data-widequran="entity" data-slug="example"></div>
```
Zero dependencies · Shadow DOM · 4 themes (light/dark/sepia/auto) · [Widget docs](https://widget.widequran.com)
## License
MIT