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:

$ pip install alfanous3

Basic Usage

Python Library

>>> from alfanous import api

# Simple search for a word
>>> api.search(u"الله")

# Advanced search with options
>>> api.do({"action": "search", "query": u"الله", "page": 1, "perpage": 10})

# Search using Buckwalter transliteration
>>> api.do({"action": "search", "query": u"Allh"})

# Get suggestions
>>> api.do({"action": "suggest", "query": u"الح"})

# Correct a query
>>> api.correct_query(u"الكتاب")

# Get metadata information
>>> api.do({"action": "show", "query": "translations"})

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:

>>> api.search(u'"الحمد لله"')

Boolean search (AND, OR, NOT):

>>> api.search(u'الصلاة + الزكاة')    # AND
>>> api.search(u'الصلاة | الزكاة')    # OR
>>> api.search(u'الصلاة - الزكاة')    # NOT

Fielded search:

>>> api.search(u'سورة:يس')           # Search in Sura Yasin
>>> api.search(u'سجدة:نعم')          # Search verses with sajda

Wildcard search:

>>> api.search(u'*نبي*')             # Words containing "نبي"

Faceted search (aggregate by fields):

>>> api.do({
...     "action": "search",
...     "query": u"الله",
...     "facets": "sura_id,juz"
... })

Documentation

API Reference

Core Functions

• api.search(query, **options) - Search Quran verses
• api.do(params) - Unified interface for all actions (search, suggest, show, list_values, correct_query)
• api.correct_query(query, unit, flags) - Get a spelling-corrected version of a query
• api.get_info(category) - Get metadata information

The underlying Raw output engine is exposed as Engine in alfanous.api (and re-exported from alfanous directly). Use it as a context manager to ensure index resources are properly released:

from alfanous.api import Engine
# or equivalently:
# from alfanous import Engine

with Engine() as engine:
    result = engine.do({"action": "search", "query": u"الله"})

Search Parameters

Common parameters for api.do() with action="search":

• query (str): Search query (required)
• unit (str): Search unit - "aya", "word", or "translation" (default: "aya")
• page (int): Page number (default: 1)
• perpage (int): Results per page, 1-100 (default: 10)
• sortedby (str): Sort order - "score", "relevance", "mushaf", "tanzil", "ayalength" (default: "score")
• reverse (bool): Reverse the sort order (default: False)
• view (str): Output view - "minimal", "normal", "full", "statistic", "linguistic" (default: "normal")
• highlight (str): Highlight style - "css", "html", "bold", "bbcode" (default: "css")

... View full README on GitHub