Skip to content
IslamencIslamencIslamenc API

Search

Two engines. Hybrid search matches by words and by meaning across the Quran, the books and the encyclopedias: a question finds what answers it even without sharing a word. Keyword search matches the words themselves, with highlighting, for autocomplete and exact lookups.

Section titled “Hybrid search”
GET/hybrid-search
Parameter
q required The question or words. Arabic or any language that has been embedded. A query in quotes is searched exactly.
type optional aya, book, card, comma-separated. Without it: all three, ranked together by relevance, at most 2 hits per book or card.
lang optional The reader’s language: searched with Arabic, and the language of each aya’s translation (default ar).
langs optional Languages to search instead, comma-separated, or all.
surah optional Surah numbers, comma-separated: ayas from these only.
book optional Book project ids: passages from these only.
enc optional Encyclopedia ids: cards from these only.
category optional Category keys "<table>:<item>", comma-separated: cards in any of them, and only cards.
prop optional A card property filter "<id>=<value>", repeatable: cards with every one, and only cards.
ratio optional Weight of meaning against words, 0 to 1 (default 0.75). 0 is words only, 1 meaning only.
exact optional true: the words as typed, together and in order, no meaning side.
limit optional 1 to 50, default 10.
offset optional Default 0; offset + limit at most 1000.
facets optional categories adds categoryCounts; props adds propCounts: matching cards per category or property value.
format optional hits: results shaped like GET /search (hits, _formatted, metadata).
intent optional off: do not narrow the types by what the question asks for (“كتاب عن…” otherwise returns books only).
Terminal window
curl "https://islamenc.com/api/hybrid-search?q=فضل الصدقة&limit=6&lang=en"
{
  "query": "فضل الصدقة",
  "filters": { "type": null, "langs": null, "surah": null, "book": null, "enc": null, "category": null, "prop": null, "ratio": 0.75, "exact": false, "intent": null },
  "semantic": true,
  "semanticHits": 18,
  "reranked": false,
  "mixed": true,
  "timings": { "embed": 0, "meili": 152, "rerank": 0, "db": 7, "total": 165 },
  "results": [
    {
      "type": "aya",
      "score": 0.7588,
      "surah_no": 2,
      "aya_no": 271,
      "surah_name": "البَقَرَة",
      "aya_uthmani": "إِن تُبۡدُواْ ٱلصَّدَقَٰتِ فَنِعِمَّا هِيَۖ ...",
      "translation": "271. If you disclose your Sadaqât (alms-giving), it is well; ...",
      "matched_lang": "ar"
    },
    {
      "type": "book",
      "score": 0.8133,
      "lang": "ar",
      "phrase_id": "17f637d4-3a97-4747-9382-4e15d7727f44",
      "book_title": "المنتقى من المتجر الرابح في ثواب العمل الصالح",
      "chapter_id": 6585,
      "project_id": 226,
      "chapter_name": "المنتقى من المتجر الرابح في ثواب العمل الصالح",
      "text": "ثواب الصدقة\nعن أبي هريرة رضي الله عنه أن رسول الله ..."
    },
    {
      "type": "card",
      "score": 0.802,
      "lang": "ar",
      "title": "الصدقة",
      "card_id": "22413",
      "enc_id": "114",
      "categories": ["11:136", "11:4", "11:511"],
      "props": { "t40": ["40:4"] },
      "text": "الصدقة\nإن من محاسن الدين الإسلامي الحث على الصدقة؛ ..."
    }
  ]
}

Result types

Section titled “Result types”
type Fields Link to
aya surah_no, aya_no, surah_name, aya_uthmani, translation (in lang), matched_lang https://islamenc.com/{lang}/quran/{surah_no}/{aya_no}
book project_id, book_title, chapter_id, chapter_name, phrase_id, lang, text (the matching passage) https://islamenc.com/{lang}/books/{project_id}
card card_id, enc_id, title, lang, text, categories, props https://islamenc.com/{lang}/enc/{enc_id}/card/{card_id}

score is the search engine’s match score (0 to 1), comparable within a type, not across types. The order of results is the ranking to show: by relevance to the question, judged by a reranker that grades every type on one scale, with no fixed turn between types.

Flags

Section titled “Flags”
Field
semantic true when the meaning side took part. false means the question’s vector was not ready within the time the API waits (about 1.5 s on a slow day) and the answer is by words alone; the vector is cached as soon as it lands, so the same question a moment later is semantic.
semanticHits How many of the candidates came from the meaning side.
mixed true for a search over several types.
timings Milliseconds spent embedding the question, in the search engine, reranking, and reading the database.

Paging and facets

Section titled “Paging and facets”

format=hits gives the shape the site’s own search page uses, with highlighting and hasMore:

Terminal window
curl "https://islamenc.com/api/hybrid-search?q=فضل الصدقة&limit=9&offset=9&format=hits&facets=categories"
{
  "hits": [
    { "id": "aya_2_271", "type": "aya", "title": "البَقَرَة - 271", "text": "...", "_formatted": { "text": "..." }, "metadata": { "surah_no": 2, "aya_no": 271, "surah_name": "البَقَرَة" } }
  ],
  "categoryCounts": { "11:4": 12, "11:136": 9 },
  "hasMore": true,
  "processingTimeMs": 165
}

Highlighting (<em> in _formatted) is only present for an exact search; a semantic match has no words to mark.

Intent

Section titled “Intent”

A question that names what it wants is narrowed to it: “كتاب عن الصيام” or “a book about fasting” returns books only, “آيات عن الصبر” ayas only, “حديث عن النية” hadith cards only. Pass intent=off to search everything regardless.

Section titled “Keyword search”
GET/search

The words themselves, with typo tolerance and highlighting. Faster than the hybrid search and the right tool for an exact phrase or an autocomplete box.

Parameter
q required The words.
type optional aya, book, card, comma-separated.
encId optional One encyclopedia’s cards only.
lang optional Language of the content searched (default Arabic with the site’s languages).
surah optional Surah number: only the ayas of that surah.
category, prop optional As in the hybrid search.
facets optional categories: adds categoryCounts.
limit, offset optional Paging. 
{
  "hits": [
    {
      "id": "aya_6546",
      "type": "aya",
      "lang": ["ar", "en"],
      "title": "آل عِمران - 17",
      "text": "ٱلصَّٰبِرِينَ وَٱلصَّٰدِقِينَ ...",
      "metadata": { "surah_no": 3, "aya_no": 17, "surah_name": "آل عِمران" },
      "_formatted": { "title": "<em>آل</em> عِمران - 17", "text": "<em>ٱلصَّٰبِرِينَ</em> ..." }
    }
  ],
  "query": "الصبر",
  "processingTimeMs": 12,
  "limit": 2,
  "offset": 0,
  "estimatedTotalHits": 1480,
  "totalHits": 1000,
  "capped": true
}

metadata carries what a hit needs to be linked: surah_no and aya_no for an aya, project_id and chapter_id for a book passage, enc_id and card_id for a card. capped says the total was cut at 1000.

Suggestions

Section titled “Suggestions”
GET/search/suggestions
Parameter
q required What has been typed so far.
type optional aya, book, card.
encId optional One encyclopedia only.
lang optional

Up to a handful of titles and passages that start with or contain the text, for an autocomplete menu:

[
  {
    "text": "الصبر وانتظار الفرج من أعظم العبادات - فضيلة الشيخ محمد بن عثيمين",
    "type": "phrase",
    "title": "مشروع هدايات - المجموعة الخامسة - الصبر وانتظار الفرج من أعظم العبادات",
    "metadata": { "phrase_id": "...", "project_id": 231, "chapter_id": 6029 },
    "snippets": [ { "id": "phrase_...", "text": "...", "_formatted": { "text": "..." } } ]
  }
]

Categories

Section titled “Categories”
GET/search/categories

Every card category across the encyclopedias, with the number of cards in each: the same shape as GET /enc/{id}/categories, for building a category filter over a search.