widequran 0.1.1

Python SDK for WideQuran — Quran surahs, ayahs, hadith collections, tafsir commentary, and Islamic encyclopedic data

widequran

Python SDK for WideQuran — access 114 surahs, 31,240 ayahs across 5 translations, 7,604 hadith from Sahih al-Bukhari, 1,896 tafsir entries from Ibn Kathir, and a comprehensive Islamic encyclopedia through a clean Python API. Includes CLI and REST API client.

WideQuran is part of the WideHoly multi-religion scripture platform, providing structured Quranic data, hadith collections, tafsir commentary, and encyclopedic content about prophets, topics, and Islamic terminology.

Explore the Quran at widequran.com — Surahs, Translations, Hadith, Tafsir, People

Table of Contents

• Install
• Quick Start
• What You'll Find on WideQuran
  • Surahs & Ayahs
  • Juz & Hizb Divisions
  • Hadith Collections
  • Tafsir Commentary
  • Prophets & Quranic Figures
• API Endpoints
• Command-Line Interface
• API Client Reference
• Learn More About the Quran
• WideHoly Scripture Platform
• License

Install

pip install widequran          # API client only
pip install widequran[cli]     # + command-line interface
pip install widequran[all]     # + CLI + MCP server

Quick Start

from widequran import WideQuran

with WideQuran() as client:
    # Get surah details — Al-Fatihah, the Opening
    surah = client.get_surah("al-fatihah")
    print(surah["name"])              # Al-Fatihah
    print(surah["verse_count"])       # 7
    print(surah["revelation_type"])   # meccan

    # Search ayahs across all translations
    results = client.search("mercy")
    for ayah in results["results"][:3]:
        print(f"{ayah['reference']}: {ayah['text'][:80]}")

    # Get hadith from Sahih al-Bukhari
    hadiths = client.list_hadiths(collection="bukhari")
    print(hadiths["results"][0]["text"][:100])

What You'll Find on WideQuran

Surahs & Ayahs

The Quran consists of 114 surahs (chapters) containing 6,236 ayahs (verses) in the original Arabic. WideQuran provides the complete Quran text with 5 translations, enabling study across languages. Each surah is classified by its revelation context — Meccan surahs (revealed before the Hijra, 610-622 CE) tend to address matters of faith and the afterlife, while Medinan surahs (revealed after the Hijra, 622-632 CE) often deal with social legislation and community affairs.

Translation	Translator	Language
Sahih International	Saheeh International	English
Yusuf Ali	Abdullah Yusuf Ali	English
Pickthall	Muhammad Marmaduke Pickthall	English
Muhsin Khan	Muhammad Muhsin Khan	English
Al-Quran (Arabic)	—	Arabic

# List all Meccan surahs — revealed in Mecca before the Hijra
meccan = client.list_surahs(revelation_type="meccan")
for s in meccan["results"][:5]:
    # Surah number, name, Arabic name, and verse count
    print(f"Surah {s['number']}: {s['name']} ({s['name_arabic']}) — {s['verse_count']} ayahs")

# Get ayahs from Al-Baqarah with Sahih International translation
ayahs = client.list_ayahs(surah="al-baqarah", translation="sahih")

Learn more: Browse Surahs · Quran Translations

Juz & Hizb Divisions

The Quran is divided into 30 equal parts called juz (plural: ajza), a system designed for completing the entire Quran during the 30 days of Ramadan. Each juz is further divided into 2 hizbs (60 total), and each hizb into 4 quarters — creating a granular framework for structured reading, memorization (hifz), and recitation schedules. This division system has been used since the early Islamic period and is marked in the margins of printed Quran copies.

Division	Count	Purpose
Juz	30	One part per day during Ramadan
Hizb	60	Half-juz markers for study pacing
Quarter	240	Fine-grained memorization segments

# Get Juz 1 — Al-Fatihah through Al-Baqarah:141
juz_1 = client.get_juz(1)
print(f"Juz {juz_1['number']}: {juz_1['name']}")
print(f"Starts: Surah {juz_1['surah_start_slug']}, Ayah {juz_1['ayah_start']}")
print(f"Ends: Surah {juz_1['surah_end_slug']}, Ayah {juz_1['ayah_end']}")

# List hizb markers within Juz 15
hizbs = client.list_hizbs(juz=15)
for h in hizbs["results"]:
    print(f"Hizb {h['number']}: Surah {h['surah_slug']}, Ayah {h['ayah_start']}")

Learn more: Juz Divisions · Quran Topics

Hadith Collections

Hadith are records of the sayings, actions, and approvals of Prophet Muhammad (peace be upon him), transmitted through chains of narrators (isnad). WideQuran includes 7,604 hadith from Sahih al-Bukhari, the most authoritative collection in Sunni Islam, compiled by Imam Muhammad ibn Ismail al-Bukhari (810-870 CE). Each hadith is graded for authenticity using the classical system developed by hadith scholars.

The Kutub al-Sittah (Six Major Collections) form the canonical hadith literature:

Collection	Compiler	Hadith Count	Period
Sahih al-Bukhari	Imam al-Bukhari	7,604	846 CE
Sahih Muslim	Imam Muslim	7,563	875 CE
Sunan Abu Dawud	Abu Dawud	5,274	889 CE
Jami at-Tirmidhi	Imam at-Tirmidhi	3,956	892 CE
Sunan an-Nasa'i	Imam an-Nasa'i	5,758	915 CE
Sunan Ibn Majah	Ibn Majah	4,341	887 CE

Hadith grading system:

Grade	Arabic	Meaning
Sahih	صحيح	Authentic — sound chain and text
Hasan	حسن	Good — acceptable chain with minor weakness
Da'if	ضعيف	Weak — unreliable narrator or broken chain
Mawdu'	موضوع	Fabricated — rejected as inauthentic

# List hadith collections available on WideQuran
collections = client.list_hadith_collections()
for c in collections["results"]:
    # Collection name, compiler, and total hadith count
    print(f"{c['name']} by {c['compiler']} — {c['hadith_count']} hadiths")

# Search hadith about prayer (salah)
results = client.search_hadith("prayer")
for h in results["results"][:3]:
    print(f"[{h['grade']}] {h['text'][:100]}")

Learn more: Hadith Collections · Islamic Glossary

Tafsir Commentary

Tafsir (exegesis) is the scholarly interpretation of the Quran, providing context, linguistic analysis, and theological explanation for each ayah. WideQuran includes 1,896 tafsir entries from Tafsir Ibn Kathir, one of the most widely referenced commentaries in the Sunni tradition, written by Ismail ibn Umar Ibn Kathir (1300-1373 CE). Ibn Kathir's methodology prioritizes interpreting the Quran through other Quranic verses (tafsir al-Quran bi-l-Quran), hadith, and reports from the companions (sahabah).

Major tafsir methodologies:

Method	Description	Example
Bi-l-Riwayah	Narration-based — relies on hadith and companion reports	Tafsir al-Tabari
Bi-l-Ra'y	Reason-based — scholarly analysis and deduction	Tafsir al-Razi
Linguistic	Focus on Arabic grammar and rhetoric	Tafsir al-Zamakhshari
Thematic	Organized by topic rather than verse order	Fi Zilal al-Quran

# List available tafsir collections
tafsirs = client.list_tafsirs()
for t in tafsirs["results"]:
    # Tafsir name, author, and language
    print(f"{t['name']} by {t['author']} ({t['language']})")

# Get tafsir entries for Surah Al-Fatihah from Ibn Kathir
entries = client.list_tafsir_entries(tafsir="ibn-kathir", surah="al-fatihah")
for e in entries["results"]:
    print(f"Ayahs {e['ayah_start']}-{e['ayah_end']}: {e['text'][:100]}")

Learn more: Tafsir Collections · Quran Glossary

Prophets & Quranic Figures

The Quran mentions 25 prophets by name, from Adam to Muhammad (peace be upon them all). Many of these prophets are shared across the Abrahamic traditions — Ibrahim (Abraham), Musa (Moses), Isa (Jesus), Dawud (David), and Sulayman (Solomon) are central figures in Judaism and Christianity as well. WideQuran provides biographical data, Quranic mention counts, and cross-religious connections for each prophet and significant figure.

Prophet	Arabic	Mentions	Also Known As
Ibrahim	إبراهيم	69	Abraham (Bible/Torah)
Musa	موسى	136	Moses (Bible/Torah)
Isa	عيسى	25	Jesus (Bible)
Nuh	نوح	43	Noah (Bible/Torah)
Yusuf	يوسف	27	Joseph (Bible/Torah)
Dawud	داود	16	David (Bible/Torah)
Sulayman	سليمان	17	Solomon (Bible/Torah)
Ayyub	أيوب	4	Job (Bible/Torah)
Yunus	يونس	4	Jonah (Bible)

# List all prophets mentioned in the Quran
prophets = client.list_people(is_prophet=True)
for p in prophets["results"]:
    # Prophet name, Arabic name, and number of Quranic mentions
    print(f"{p['name']} ({p['name_arabic']}) — mentioned {p['mentioned_count']} times")

# Get details for Prophet Ibrahim (Abraham)
ibrahim = client.get_person("ibrahim")
print(f"{ibrahim['name']}: {ibrahim['description'][:200]}")

Learn more: Quranic People · Quranic Topics

API Endpoints

Method	Endpoint	Description
GET	/api/v1/quran/surahs/	List all 114 surahs
GET	/api/v1/quran/surahs/{slug}/	Surah details
GET	/api/v1/quran/translations/	List translations
GET	/api/v1/quran/translations/{code}/	Translation details
GET	/api/v1/quran/ayahs/	List ayahs (filter by surah, translation; search)
GET	/api/v1/quran/ayahs/{id}/	Ayah details
GET	/api/v1/quran/juz/	List 30 juz
GET	/api/v1/quran/juz/{number}/	Juz details
GET	/api/v1/quran/hizbs/	List hizb markers
GET	/api/v1/quran/hizbs/{number}/	Hizb details
GET	/api/v1/quran/tafsirs/	List tafsir collections
GET	/api/v1/quran/tafsirs/{slug}/	Tafsir details
GET	/api/v1/quran/tafsir-entries/	List tafsir entries (filter by tafsir, surah)
GET	/api/v1/quran/tafsir-entries/{id}/	Tafsir entry details
GET	/api/v1/quran/hadith-collections/	List hadith collections
GET	/api/v1/quran/hadith-collections/{slug}/	Hadith collection details
GET	/api/v1/quran/hadiths/	List hadiths (filter by collection, grade; search)
GET	/api/v1/quran/hadiths/{id}/	Hadith details
GET	/api/v1/quran/people/	List Quranic people (filter by is_prophet)
GET	/api/v1/quran/people/{slug}/	Person details
GET	/api/v1/quran/topics/	List Quranic topics
GET	/api/v1/quran/topics/{slug}/	Topic details
GET	/api/v1/quran/glossary/	List Islamic glossary terms
GET	/api/v1/quran/glossary/{slug}/	Glossary term details

Example

curl -s "https://widequran.com/api/v1/quran/surahs/al-fatihah/"

{
  "id": 1,
  "number": 1,
  "name": "Al-Fatihah",
  "slug": "al-fatihah",
  "name_arabic": "الفاتحة",
  "name_transliteration": "Al-Fatihah",
  "meaning": "The Opening",
  "revelation_type": "meccan",
  "verse_count": 7,
  "order_of_revelation": 5,
  "description": "The Opening chapter of the Quran...",
  "url": "/surahs/al-fatihah/"
}

Full API documentation at widequran.com/developers/. OpenAPI 3.1.0 spec: widequran.com/api/schema/.

Command-Line Interface

pip install widequran[cli]

# Surah details
widequran surah al-fatihah

# List all surahs (optionally filter by type)
widequran surahs --type meccan

# Get a specific ayah
widequran ayah al-fatihah 1

# Search ayahs across the Quran
widequran search "mercy"

# Get a hadith by collection and number
widequran hadith bukhari 1

# Juz details
widequran juz 1

# Tafsir information
widequran tafsir ibn-kathir

# Quranic person details
widequran person ibrahim

API Client Reference

Method	Parameters	Description
list_surahs()	revelation_type	List all 114 surahs
get_surah(slug)	—	Get surah by slug
list_translations()	language	List translations
get_translation(code)	—	Get translation by code
list_ayahs()	surah, translation, search	List/filter/search ayahs
get_ayah(id)	—	Get ayah by ID
search(query)	surah	Search ayahs by text
list_juz()	—	List 30 juz
get_juz(number)	—	Get juz by number (1-30)
list_hizbs()	juz	List hizb markers
get_hizb(number)	—	Get hizb by number
list_tafsirs()	—	List tafsir collections
get_tafsir(slug)	—	Get tafsir by slug
list_tafsir_entries()	tafsir, surah	List/filter tafsir entries
get_tafsir_entry(id)	—	Get tafsir entry by ID
list_hadith_collections()	—	List hadith collections
get_hadith_collection(slug)	—	Get collection by slug
list_hadiths()	collection, grade, search	List/filter/search hadith
get_hadith(id)	—	Get hadith by ID
search_hadith(query)	collection	Search hadith by text
list_people()	is_prophet	List Quranic people
get_person(slug)	—	Get person by slug
list_topics()	—	List Quranic topics
get_topic(slug)	—	Get topic by slug
list_glossary()	—	List glossary terms
get_term(slug)	—	Get glossary term by slug

Learn More About the Quran

• Browse: Surahs · Translations · Juz Divisions
• Study: Hadith Collections · Tafsir Commentary
• Reference: Quranic People · Topics · Glossary
• API: Developer Documentation · OpenAPI Spec

WideHoly Scripture Platform

WideQuran is part of the WideHoly multi-religion scripture platform.

Site	Domain	Focus
WideBible	widebible.com	Bible — 66 books, 31,102 verses, 7 translations, cross-references
WideQuran	widequran.com	Quran — 114 surahs, 31,240 ayahs, hadith, tafsir
WideTorah	widetorah.com	Torah — 24 Tanakh books, Talmud, Mishnah, Rashi
WideSutra	widesutra.com	Buddhist sutras — Tipitaka, Mahayana, Zen texts
WideGita	widegita.com	Bhagavad Gita — 18 chapters, 700 shlokas, commentaries
WideHoly	wideholy.com	Hub — cross-religion search, shared figures, comparative study

License

MIT