Comprehending Quran

Java API Documentation

Programmatic access to the Quranic Arabic Corpus

Getting Started

Download the Java library and include it in your project:

<dependency>
    <groupId>org.quraniccorpus</groupId>
    <artifactId>quran-api</artifactId>
    <version>2.0.1</version>
</dependency>

Quick Start Example

import org.quraniccorpus.*;

public class QuranExample {
    public static void main(String[] args) {
        // Initialize API
        QuranAPI api = new QuranAPI();
        
        // Get word details from Surah 1, Verse 1, Word 1
        WordDetails word = api.getWordDetails(1, 1, 1);
        System.out.println("Arabic: " + word.getArabic());
        System.out.println("Translation: " + word.getTranslation());
        System.out.println("Root: " + word.getRoot());
        
        // Search for words by root
        List<WordOccurrence> results = api.searchByRoot("علم");
        for (WordOccurrence occ : results) {
            System.out.println(occ.getSurah() + ":" + occ.getVerse());
        }
        
        // Get full verse
        Verse verse = api.getVerse(1, 1);
        System.out.println("Full verse: " + verse.getArabic());
    }
}

API Reference

QuranAPI()

Constructor that initializes the API with default settings.

getWordDetails(int surah, int verse, int wordNumber)

Returns detailed information about a specific word.

Parameters:
  • surah - Chapter number (1-114)
  • verse - Verse number (1-286)
  • wordNumber - Word position in the verse
Returns: WordDetails object

getVerse(int surah, int verse)

Retrieves complete verse information.

Returns: Verse object with full text and words

searchByRoot(String root)

Finds all occurrences of words derived from a specific root.

Returns: List<WordOccurrence>

searchByWord(String word)

Searches for exact word matches across the Quran.

Returns: List<WordOccurrence>

Data Models

WordDetails

  • getArabic() - Returns Arabic text
  • getTransliteration() - Returns transliteration
  • getTranslation() - Returns English translation
  • getRoot() - Returns root letters
  • getPartOfSpeech() - Returns grammatical category
  • getMorphology() - Returns Morphology object

Morphology

  • getForm() - Derived verb form (I-X)
  • getTense() - Perfect, imperfect, imperative
  • getGender() - Masculine or feminine
  • getNumber() - Singular, dual, plural
  • getCase() - Nominative, accusative, genitive

Advanced Usage

// Get all occurrences of a root with frequency
Map<String, Integer> stats = api.getRootStatistics("رح م");
System.out.println("Root 'ر ح م' appears " + stats.get("count") + " times");

// Get morphological pattern analysis
PatternAnalysis pattern = api.analyzePattern("فاعل");
System.out.println("Pattern meaning: " + pattern.getDescription());

// Batch processing example
Verse[] verses = api.getVersesBySurah(1);
for (Verse verse : verses) {
    for (Word word : verse.getWords()) {
        processWord(word);
    }
}

Troubleshooting

Q: How do I handle large datasets?

A: Use the streaming API for batch processing: QuranAPI.streamVerses()

Q: Can I use this offline?

A: Yes, the library includes a local database. Initialize with new QuranAPI("local")

Q: How do I update the data?

A: Call api.updateDatabase() to fetch the latest version