Alfanous-team / alfanous

Alfanous API **Alfanous** is a Quranic search engine API that provides simple and advanced search capabilities for the Holy Qur'an. It enables developers to build applications that search through Quranic text in Arabic, with support for Buckwalter transliteration, advanced query syntax, and rich metadata. Features • **Powerful Search**: Search Quranic verses with simple queries or advanced Boolean logic • **Arabic Support**: Full support for Arabic text and Buckwalter transliteration • **Rich Metadata**: Access verse information, translations, recitations, and linguistic data • **Flexible API**: Use as a Python library or RESTful web service • **Faceted Search**: Aggregate results by Sura, Juz, topics, and more • **Multiple Output Formats**: Customize output with different views and highlight styles Quickstart Installation Install from PyPI using pip: Basic Usage Python Library Web Service You can also use the public web service: • Search: http://alfanous.org/api/search?query=الله • With transliteration: http://alfanous.org/api/search?query=Allh Or run your own web service locally (see alfanous_webapi). Quick Examples Search for phrases: Boolean search (AND, OR, NOT): Fielded search: Wildcard search: Faceted search (aggregate by fields): Documentation API Reference Core Functions • - Search Quran verses • - Unified interface for all actions (search, suggest, show, list_values, correct_query) • - Get a spelling-corrected version of a query • - Get metadata information The underlying output engine is exposed as in (and re-exported from directly). Use it as a context manager to ensure index resources are properly released: Search Parameters Common parameters for with : • (str): Search query (required) • (str): Search unit - "aya", "word", or "translation" (default: "aya") • (int): Page number (default: 1) • (int): Results per page, 1-100 (default: 10) • (str): Sort order - "score", "relevance", "mushaf", "tanzil", "ayalength" (default: "score") • (bool): Reverse the sort order (default: False) • (str): Output view - "minimal", "normal", "full", "statistic", "linguistic" (default: "normal") • (str): Highlight style - "css", "html", "bold", "bbcode" (default: "css") • (str): Text script - "standard" or "uthmani" (default: "standard") • (bool): Include Arabic vocalization (default: True) • (str): Translation ID to include • (str): Recitation ID to include (1-30, default: "1") • (bool): Enable fuzzy search — searches both (exact) and (normalised/stemmed) fields, plus Levenshtein distance matching (default: False). See Exact Search vs Fuzzy Search. • (int): Maximum Levenshtein edit distance for fuzzy term matching — , , or (default: , only used when ). • (str): Comma-separated list of fields for faceted search • (dict): Filter results by field values For a complete list of parameters and options, see the detailed documentation. Advanced Features Exact Search vs Fuzzy Search Alfanous provides two complementary search modes that control which index fields are queried. Exact Search (default — ) When fuzzy search is **off** (the default), queries run against the ** ** field, which stores the fully-vocalized Quranic text with diacritical marks (tashkeel) preserved. This mode is designed for precise, statistical matching: • Diacritics in the query are significant — and are treated as different words. • No stop-word removal, synonym expansion, or stemming is applied to the query. • Ideal when you need exact phrase matches, reproducible result counts, or statistical analysis. Fuzzy Search ( ) When fuzzy search is **on**, queries run against **both** the field (exact matches) **and** the field (a separate index built for broad, forgiving search). At index time the field is processed through a richer pipeline: • **Normalisation** — shaped letters, tatweel, hamza variants and common spelling errors are unified. • **Stop-word removal** — high-frequency function words (e.g. مِنْ، فِي، مَا) are filtered out so they do not dilute result relevance. • **Synonym expansion** — each token is stored together with its synonyms, so a query for one word automatically matches equivalent words. • **Arabic stemming** — words are reduced to their stem using the Snowball Arabic stemmer (via ), so different morphological forms of the same root match each other. No heavy operations are performed on the query string at search time; all the linguistic enrichment lives in the index. Additionally, for each Arabic term in the query, a **Levenshtein distance** search is performed against the field (unvocalized, non-stemmed). This catches spelling variants and typos within a configurable edit-distance budget controlled by . | | Behaviour | |---|---| | (default) | Catches single-character insertions, deletions, or substitutions | | | Broader tolerance — useful for longer words or noisy input | | | Maximum supported — use with care as recall increases significantly | Fuzzy mode is particularly useful when: • The user does not know the exact vocalized form of a word. • You want morphologically related words to appear in the same result set (e.g. searching *كتب* also surfaces *كتاب*, *كاتب*, *مكتوب*). • You want synonym-aware retrieval without writing explicit OR queries. > **Note:** must be installed for stemming to take effect ( ). If the package is absent the stem filter degrades silently to a no-op, leaving normalisation and stop-word removal still active. List Field Values returns every unique indexed value for a given field. Use it to discover the full vocabulary of searchable fields — for example, all available translation identifiers, part-of-speech tags, or root words — before composing a query. **Parameters:** • (str): The name of the indexed field whose unique values you want (required). **Return value:** A dictionary with a key containing: • — the requested field name. • — sorted list of unique non-empty indexed values. • — length of the list. Query Correction uses Whoosh's built-i…