Awesome Open Source
Awesome Open Source

Alfanous API

Authors: Authors.rst
Release: 0.7.30
License: AGPL
Tracker: Alfanous-team/alfanous/Issues
Mailinglist: [email protected]

Usage

Install it from Pypi:

$ sudo pip install alfanous

You can use it from console:

$ alfanous-console -a search -q
$ alfanous-console -a search -q Allh

or from Python:

>>> import alfanous
>>> alfanous.search(u"")
>>> alfanous.do({"action":"search","query":u""})
>>> alfanous.do({"action":"search","query":u"Allh"}) # Buckwalter transliteration

You can use it also from the web service:

http://alfanous.org/api/search?query=

http://alfanous.org/api/search?query=Allh

Flags

number flag related action related unit description default value accepted values
1 action <none> <none> action to perform "search" search | suggest | show
2 unit search, suggest <none> search unit "aya" aya | word | translation
2 ident <all> <all> identifier of requester [experimental] "undefined" undefined
3 platform <all> <all> platform used by requester "undefined" undefined | wp7 | s60 | android | ios | linux | window
4 domain <all> <all> web domain of requester if applicable "undefined" *
5a query search,suggest <all> query attached to action "" *
5b query show <all> query attached to action "" all | translations |recitations | information | hints | surates | chapters | defaults | flags | fields | fields_reverse | errors | domains | help_messages | roots
6 highlight search <all> highlight method "css" css | html | genshi | bold | bbcode
7 script search aya, word script of aya text "standard" standard | uthmani
8 vocalized search aya, word enable vocalization of aya text "True" True | False
9 recitation search aya recitation id "1" 1 to 30
10 translation search aya, trans translation id "None" *
11 romanization search aya, word type of romanization "none" none | buckwalter | iso | arabtex
12a view search aya, word pre-defined configuration for view "custom" minimal | normal | full | statistic | linguistic | custom
12b view search translation pre-defined configuration for view "custom" minimal | normal | full | custom
13 prev_aya search aya enable previous aya retrieving "False" True | False
14 next_aya search aya enable next aya retrieving "False" True | False
15 sura_info search aya enable sura information retrieving "True" True | False
16 sura_stat_info search aya enable sura stats retrieving "False" True | False
17 word_info search aya, word enable word information retrieving "True" True | False
17a word_synonyms search aya enable retrieving of keyword synonyms "False" True | False
17b word_derivations search aya enable retrieving of keyword derivations "True" True | False
17c word_vocalizations search aya enable retrieving of keyword vocalizations "True" True | False
18 aya_position_info search aya enable aya position information retrieving "True" True | False
19 aya_theme_info search aya enable aya theme information retrieving "True" True | False
20 aya_stat_info search aya enable aya stat information retrieving "True" True | False
21 aya_sajda_info search aya enable aya sajda information retrieving "True" True | False
22 annotation_word search aya, word enable query terms annotations retrieving "False" True | False
23 annotation_aya search aya enable aya words annotations retrieving "False" True | False
24 sortedby search aya sorting order of results "score" total | score | mushaf | tanzil | subject
25 offset search <all> starting offset of results "1" 1 to 6236
26 range search <all> range of results "10" 1 to 25
27 page search <all> page number [override offset] "1" 1 to 6236
28 perpage search <all> results per page [override range] "10" 1 to 25
29 fuzzy search aya fuzzy search [exprimental] "False" True | False
30 aya search word,trans enable retrieving of aya text "True" True | False

Advanced Query Examples

Aya Search:

  • Simple search:
  • Phrases : " "
  • Logical relations - ANDNOT : ( - )
  • Logical relations - AND : +
  • Logical relations - OR : |
  • Joker * : **
  • Joker ? :
  • Fielded search : : ( look for other Fields_ )
  • Fielded search (2) : :
  • Intervals : _:[1 5]
  • Partial vocalization : _:''
  • Tuples (root,type= | | ) as: {}
  • Derivations - lemma : >
  • Derivations - root : >>

Translation Search:

  • Exact search: god
  • Phrase search: "seven heavens"
  • Logical relations - OR: prayer ANDNOT charity
  • Logical relations - AND: prayer AND charity
  • Logical relations - OR: prayer OR charity
  • Wildcards - Joker *: pray*
  • Wildcards - Joker ?: produc?
  • Fielded search: lang:fr
  • Fielded search (2) : author:Shakir

Fields

  • Aya Search Fields:

SortedBy Options

  • Aya Search:
Option Description
score The relevance of the results compared to the query keywords
mushaf The default order of ayas in Mus-haf
tanzil The revelation order
subject The alphabetic order of the values for subjects fields
ayalenght The length of ayah from the shortest to the longest
FIELD The numerical order or alphabetic order of a costum field (see Fields_ )

Schema Samples

  • Aya Search:

Suggestions

flags:

{
    "action"="suggest",
    "query"=""
}

response:

{
"suggest": [
              ["\u0645\u0621\u0635\u062f\u0629",
                  ["\u0645\u0642\u062a\u0635\u062f\u0629", "\u0645\u0624\u0635\u062f\u0629"]
              ]
            ],
"error": {
            "msg": "success ## action=suggest ; query=\u0645\u0621\u0635\u062f\u0629",
            "code": 0
           }
}

Results

flags:

{
   "action":"search",
   "query": "",
   "sortedby":"score",
   "page": 1,
   "word_info":True,
   "highlight":"css",
   "script": "standard",
   "prev_aya": True,
   "next_aya": True,
   "sura_info": True,
   "aya_position_info":  True,
   "aya_theme_info":  True,
   "aya_stat_info":  True,
   "aya_sajda_info":  True,
   "annotation_word": True,
   "annotation_aya": True,
   "translation":"None",
   "recitation": 1

 }

response:

{

    "search": {
                "runtime": 1.0951571464538574,
                "interval": {
                                "start": 1,
                                "total": 1,
                                "end": 1
                            }
                "words": {
                            "global": {
                                        "nb_words": 1,
                                        "nb_matches": 1,
                                        "nb_vocalizations": 1,
                                        },
                            "individual": {

                                                            "1": {
                                                                    "word": "\u0627\u0644\u0643\u0648\u062b\u0631",
                                                                    "nb_matches": 1,
                                                                    "nb_ayas": 1,
                                                                    "nb_vocalizations": 1,
                                                                    "vocalizations": ["\u0627\u0644\u0652\u0643\u064e\u0648\u0652\u062b\u064e\u0631\u064e"],
                                                                  },
                                                           },

                         },

                "ayas": {
                            "1": {

                                        "identifier": {
                                                            "gid": 6205,
                                                            "aya_id": 1,
                                                            "sura_id": 108,
                                                            "sura_name": "\u0627\u0644\u0643\u0648\u062b\u0631",

                                                         },
                                        "aya": {
                                                "id": 1,
                                                "text": "\u0625\u0650\u0646\u0651\u064e\u0627 \u0623\u064e\u0639\u0652\u0637\u064e\u064a\u0652\u0646\u064e\u0627\u0643\u064e <span class=\"match term0\">\u0627\u0644\u0652\u0643\u064e\u0648\u0652\u062b\u064e\u0631\u064e</span>",
                                                "recitation": "http://www.everyayah.com/data/Abdul_Basit_Murattal_64kbps/108001.mp3",
                                                "translation": null,
                                                "prev_aya": {
                                                                "id": 7,
                                                                "sura": "\u0627\u0644\u0645\u0627\u0639\u0648\u0646",
                                                                "text": "\u0648\u064e\u064a\u064e\u0645\u0652\u0646\u064e\u0639\u064f\u0648\u0646\u064e \u0627\u0644\u0652\u0645\u064e\u0627\u0639\u064f\u0648\u0646\u064e",
                                                            },
                                                "next_aya": {
                                                                "id": 2,
                                                                "sura": "\u0627\u0644\u0643\u0648\u062b\u0631",
                                                                "text": "\u0641\u064e\u0635\u064e\u0644\u0651\u0650 \u0644\u0650\u0631\u064e\u0628\u0651\u0650\u0643\u064e \u0648\u064e\u0627\u0646\u0652\u062d\u064e\u0631\u0652",
                                                            },
                                                },


                                        "sura": {
                                                    "id": 108,
                                                    "name": "\u0627\u0644\u0643\u0648\u062b\u0631",
                                                    "type": "\u0645\u0643\u064a\u0629",
                                                    "order": 15,
                                                    "ayas": 3,
                                                    "stat": {
                                                                "words": 10,
                                                                "letters": 42,
                                                                "godnames": 0,

                                                              },
                                                },
                                        "theme": {
                                                            "chapter": "\u0623\u0631\u0643\u0627\u0646 \u0627\u0644\u0625\u0633\u0644\u0627\u0645 ",
                                                            "topic": "\u0627\u0644\u062d\u062c \u0648\u0627\u0644\u0639\u0645\u0631\u0629 ",
                                                            "subtopic": null
                                                  },


                                        "position": {
                                                        "rub": 0,
                                                        "manzil": 7,
                                                        "ruku": 550,
                                                        "hizb": 60,
                                                        "page": 602
                                                    },
                                        "sajda": {
                                                    "exist": false,
                                                    "id": null,
                                                    "type": null
                                                 },

                                        "stat": {
                                                    "letters": 16,
                                                    "godnames": 0,
                                                    "words": 3
                                                },
                                        "annotations": {
                                                            "1": {
                                                                    "arabicroot": null,
                                                                    "arabicmood": null,
                                                                    "number": null,
                                                                    "spelled": "\u0627\u0646\u0627\u0653",
                                                                    "aspect": null,
                                                                    "word_gid": 75871,
                                                                    "word_id": 1,
                                                                    "mood": null,
                                                                    "arabicspecial": "\u0625\u0650\u0646\u0651",
                                                                    "state": null,
                                                                    "arabiclemma": "\u0625\u0650\u0646\u0651",
                                                                    "gid": 116333,
                                                                    "type": "Particles",
                                                                    "aya_id": 1,
                                                                    "arabictoken": null,
                                                                    "form": null,
                                                                    "pos": "Accusative particle",
                                                                    "arabiccase": "\u0645\u0646\u0635\u0648\u0628",
                                                                    "part": "\u062c\u0630\u0639",
                                                                    "normalized": "\u0625\u0646\u0627\u0653",
                                                                    "case": "Accusative case",
                                                                    "sura_id": 108,
                                                                    "word": "\u0625\u0650\u0646\u0651\u064e\u0627\u0653",
                                                                    "derivation": null,
                                                                    "arabicpos": "\u062d\u0631\u0641 \u0646\u0635\u0628",
                                                                    "person": null,
                                                                    "token": null,
                                                                    "gender": null,
                                                                    "voice": null,
                                                                    "order": 1
                                                                 },
                                                            "2": {
                                                                    "arabicroot": "\u0639\u0637\u0648",
                                                                    "arabicmood": null,
                                                                    "number": "\u062c\u0645\u0639",
                                                                    "spelled": "\u0627\u0639\u0637\u064a\u0646\u0670\u0643",
                                                                    "aspect": "Perfect verb",
                                                                    "word_gid": 75872,
                                                                    "word_id": 2,
                                                                    "mood": null,
                                                                    "arabicspecial": null,
                                                                    "state": null,
                                                                    "arabiclemma": null,
                                                                    "gid": 116335,
                                                                    "type": "Verbs",
                                                                    "aya_id": 1,
                                                                    "arabictoken": null,
                                                                    "form": "Fourth form",
                                                                    "pos": "Verb",
                                                                    "arabiccase": null,
                                                                    "part": "\u062c\u0630\u0639",
                                                                    "normalized": "\u0623\u0639\u0637\u064a\u0646\u0670\u0643",
                                                                    "case": null,
                                                                    "sura_id": 108,
                                                                    "word": "\u0623\u064e\u0639\u0652\u0637\u064e\u064a\u0652\u0646\u064e\u0670\u0643\u064e",
                                                                    "derivation": null,
                                                                    "arabicpos": "\u0641\u0639\u0644",
                                                                    "person": "\u0645\u062a\u0643\u0644\u0645",
                                                                    "token": null,
                                                                    "gender": "\u0645\u0630\u0651\u0643\u0631",
                                                                    "voice": null,
                                                                    "order": 1
                                                                 },
                                                            "3": {
                                                                    "arabicroot": null,
                                                                    "arabicmood": null,
                                                                    "number": null,
                                                                    "spelled": "\u0671\u0644\u0643\u0648\u062b\u0631",
                                                                    "aspect": null,
                                                                    "word_gid": 75873,
                                                                    "word_id": 3,
                                                                    "mood": null,
                                                                    "arabicspecial": null,
                                                                    "state": null,
                                                                    "arabiclemma": null,
                                                                    "gid": 116337,
                                                                    "type": "determiner",
                                                                    "aya_id": 1,
                                                                    "arabictoken": "\u0627\u0644",
                                                                    "form": null,
                                                                    "pos": null,
                                                                    "arabiccase": null,
                                                                    "part": "\u0633\u0627\u0628\u0642",
                                                                    "normalized": "\u0671\u0644\u0643\u0648\u062b\u0631",
                                                                    "case": null,
                                                                    "sura_id": 108,
                                                                    "word": "\u0671\u0644\u0652\u0643\u064e\u0648\u0652\u062b\u064e\u0631\u064e",
                                                                    "derivation": null,
                                                                    "arabicpos": null,
                                                                    "person": null,
                                                                    "token": "al",
                                                                    "gender": null,
                                                                    "voice": null,
                                                                    "order": 1
                                                                 }
                                                        },
                                            },
                        },
                "translation_info": {},
                },

    "error": {
                "code": 0,
                "msg": "success ## action=search ; query=\u0627\u0644\u0643\u0648\u062b\u0631",
             }
    }

Translations

TODO

Information

flags:

{
    "action"="show",
    "query"="information"
}

response:

{
    "show": {
        "information": {
            "engine": "Alfanous",
            "wiki": "http://wiki.alfanous.org/doku.php?id=json_web_service",
            "description": "Alfanous is a Quranic search engine provides simple and advanced search services in the diverse information of the Holy Quran .",
            "author": "Assem chelli",
            "version": "0.5",
            "contact": "[email protected]",
            "console_note": "this is console interface of Alfanous, try -h to get help ",
            "json_output_system_note": "\n    This is the <a href='http://json.org/'>JSON</a> output system of <a href=\"http://wiki.alfanous.org\">Alfanous</a> project .This feature is in Alpha test and the Json schema may be it's not stable . We are waiting for real feadbacks and suggestions to improve its efficacity,quality and stability. To contact the author ,please send a direct email to <b> assem.ch[at]gmail.com</b> or to the mailing list <b>alfanous [at] googlegroups.com</b>\n    <br/><br/> For more details  visit the page of this service <a href=\"http://wiki.alfanous.org/doku.php?id=json_web_service\">here</a>\n    "
        }
    },
    "error": {
        "msg": "success ## action=show ; query=information",
        "code": 0
    }
}

Recitations

flags:

{
    "action"="show",
    "query"="recitations"
}

response (sample):

{
    "show": {
        "recitations": {
            "45": {
                "bitrate": "192kbps",
                "name": "English/Ibrahim Walk TEST",
                "subfolder": "English/Ibrahim_Walk_192kbps_TEST"
            },
            "54": {
                "bitrate": "128kbps",
                "name": "Salah Al Budair",
                "subfolder": "Salah_Al_Budair_128kbps"
            }


        }
    },
    "error": {
        "msg": "success ## action=show ; query=recitations",
        "code": 0
    }
}

Fields

flags:

{
    "action"="show",
    "query"="fields"
}

response:

{
    "show": {
        "fields": {
            "": "juz",
            " ": "uth",
            "_": "sura_type",
            "_": "sajda_id",
            "": "page",
            "": "rub",
            "_": "s_r",
            "": "ruku",
            "_": "sura_id",
            "_": "s_a",
            "_": "aya_",
            "": "subject",
            "_": "s_g",
            "_": "a_w",
            "": "chapter",
            "_": "a_l",
            "": "sura",
            "": "topic",
            "": "aya",
            "_": "aya_id",
            "_": "uth_",
            "_": "s_w",
            "_": "sajda_type",
            "": "gid",
            "": "subtopic",
            "": "nisf",
            "_": "s_l",
            "": "hizb",
            "": "manzil",
            "_": "a_g",
            "": "sajda",
            "_": "sura_order"
        }
    },
    "error": {
        "msg": "success ## action=show ; query=fields",
        "code": 0
    }
}

Hacking

Build

The API uses many critical resources that must be downloaded and/or prepared to be used. To do that, just run this command in the root path of the project

  1. Install all building dependencies: pyparsing, epydoc, sphinx.

    • (ubuntu 12.04):

      $ sudo apt-get install python-qt4 qt4-dev-tools python-qt4-dev pyqt4-dev-tools
      $ sudo apt-get install python-distutils-extra
      $ sudo easy_install pyparsing epydoc sphinx
      
  2. Run the build command:

    $ cd ../../
    $ make build
    

For more details check Makefile

Install

To install the API from the source (After Build ):

$ sudo python setup.py install

A console interface will be installed automatically with the API:

$ alfanous-console -h
usage: alfanous-console [flags]

note: if you are looking for alfanous legacy code, you can find it under legacy branch

Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Python (806,104
Search (31,595
Indexing (2,588
Search Engine (2,566
Arabic (1,483
Django Application (1,417
Quran (474