A Developer's Guide to the Structured Quran Database

Looking for a clean, structured dataset of the Quran for your next project? Whether you're building a language learning app, conducting computational linguistics research, or creating a personal reference tool, finding a well-organized, machine-readable version of the Quran can be a chore. Most available data is either unstructured or locked inside complex applications.

That's where the quran-database repository comes in. It's a comprehensive, developer-first dataset that turns the entire Quran into a set of accessible JSON files, ready to be plugged into your code.

What It Does

In short, this project is a complete, structured database of the Quran. It breaks down the entire text into a logical, query-friendly format. The data is meticulously organized by chapters (Surahs) and verses (Ayahs), with each entry containing not just the Arabic text, but also transliteration, translation, and associated metadata. It's designed to be a foundational dataset you can build on, without having to parse PDFs or scrape websites.

Why It's Cool

The real value here is in the thoughtful structure and the multiple access points it provides. Here’s what makes it stand out:

• Multiple Data Formats: You get the data in both a single, massive quran.json file and a split version (one file per Surah), which is perfect for lazy loading in web or mobile apps.
• Rich Metadata: Each verse includes the Arabic text, a standardized transliteration, and an English translation. It also includes chapter and verse numbers, making cross-referencing and display a breeze.
• Developer Ready: It's just JSON. You can import it directly into JavaScript/Node.js projects, parse it with Python's json library, or load it into any database (like SQLite or PostgreSQL) with a simple script. There's no proprietary format to wrestle with.
• Clear Licensing: The project is open-source under the MIT License, so you can use it freely in personal, academic, or commercial projects.

How to Try It

Getting started is as simple as cloning the repo. There's no API server to set up or complex dependencies to install.

1. Head over to the GitHub repository: github.com/AbdullahGhanem/quran-database
2. Clone it to your local machine:

   git clone https://github.com/AbdullahGhanem/quran-database.git
   

3. Navigate into the data directory. You'll find the main quran.json file and the split folder.
4. Start exploring. Here's a quick Python example to get the first verse:

   import json
   
   with open('quran-database/data/quran.json', 'r', encoding='utf-8') as f:
       data = json.load(f)
   
   first_verse = data[0] # The data is an array of verses
   print(f"{first_verse['surah_name']} ({first_verse['surah_number']}:{first_verse['ayah_number']})")
   print(first_verse['text'])
   print(first_verse['translation'])
   

Final Thoughts

As a developer, finding a reliable, structured dataset is often half the battle. This project elegantly solves that problem for a specific but important domain. It's the kind of utility that removes friction, letting you focus on building your application's unique features instead of data wrangling. Whether you're analyzing linguistic patterns, building a search interface, or just creating a personal digital copy, this database is an incredibly useful resource to have in your toolkit.

Follow us for more cool projects: @githubprojects