कुरान AI खोज API

अवलोकन

AI खोज API सिमेंटिक AI का उपयोग करके कुरान में सूरह और आयतों से प्राकृतिक-भाषा प्रश्नों का मिलान करता है। इसे उन इंटीग्रेटर्स के लिए डिज़ाइन किया गया है जो अपना स्वयं का खोज इंडेक्स या LLM पाइपलाइन बनाए बिना विषय-आधारित खोज चाहते हैं।

• एक एकल JSON प्रतिक्रिया लौटाता है जिसे आप किसी भी HTTP क्लाइंट के साथ पार्स कर सकते हैं।
• प्रत्येक परिणाम की प्रासंगिकता संक्षिप्त विवरण आपके द्वारा पास की गई भाषा में लिखता है, या जब आप इसे छोड़ देते हैं तो क्वेरी भाषा (detectedLanguage) को स्वतः पता लगाता है।
• संरचित सूरह और आयत संख्याएँ लौटाता है जिनसे आपका ऐप लिंक कर सकता है।

एंडपॉइंट

उपयोगकर्ता के खोज वाक्यांश के साथ एक JSON बॉडी भेजें। API मिलान किए गए संदर्भों वाले एक एकल JSON ऑब्जेक्ट के साथ प्रतिक्रिया देता है।

POST https://openquran.app/api/ai-search

हेडर

अनुरोध

अनुरोध निकाय एक एकल JSON ऑब्जेक्ट है:

{
  "query": "patience in hardship",
  "language": "en"
}

बाधाएँ

• ट्रिमिंग के बाद क्वेरी 2–300 वर्णों की होनी चाहिए।
• भाषा वैकल्पिक है: प्रासंगिकता स्पष्टीकरणों के लिए एक ISO 639-1 कोड (जैसे en, ar, fr)। जब इसे छोड़ा जाता है या अमान्य होता है, तो भाषा क्वेरी से स्वतः पता लगाई जाती है।
• प्रति क्वेरी अधिकतम 12 परिणाम।
• शुरुआती और अंतिम रिक्त स्थान हटा दिए जाते हैं।

प्रतिक्रिया

सफल अनुरोध HTTP 200 के साथ एक JSON ऑब्जेक्ट लौटाते हैं।

सामग्री-प्रकार: application/json

{
  "ok": true,
  "results": [
    {
      "type": "surah",
      "surah": 2,
      "relevance": "Covers patience through trials."
    },
    {
      "type": "verse",
      "surah": 2,
      "ayah": 255,
      "relevance": "Ayat al-Kursi speaks of steadfastness in faith."
    }
  ],
  "detectedLanguage": "en"
}

परिणामों में प्रत्येक आइटम में एक प्रासंगिकता फ़ील्ड शामिल है। वह पाठ आपके द्वारा अनुरोधित भाषा में लिखा गया है, या जब कोई भाषा प्रदान नहीं की गई थी तो पता लगाई गई क्वेरी भाषा (detectedLanguage) में — उदाहरण के लिए, एक अरबी क्वेरी अरबी प्रासंगिकता संक्षिप्त विवरण देती है।

शीर्ष-स्तरीय फ़ील्ड

परिणाम के प्रकार

प्रत्येक परिणाम एक टैग किया गया ऑब्जेक्ट है — या तो एक पूरी सूरह या एक एकल आयत:

// Whole surah reference
{ "type": "surah", "surah": 2, "relevance": "One sentence explaining the match." }

// Single verse reference
{ "type": "verse", "surah": 2, "ayah": 255, "relevance": "One sentence explaining the match." }

• surah — सूरह संख्या, 1–114।
• ayah — सूरह के भीतर 1-आधारित आयत संख्या (केवल आयत परिणामों के लिए)।
• relevance — संदर्भ क्यों मेल खाता है, इसका एक-वाक्य स्पष्टीकरण, अनुरोधित भाषा या पता लगाई गई क्वेरी भाषा में लिखा गया। त्वरित-संदर्भ लुकअप के लिए शून्य।

त्वरित संदर्भ

केवल सूरह संख्याएँ और आयत संदर्भ AI मॉडल को छोड़ देते हैं और तुरंत हल हो जाते हैं:

• 2 — सूरह 2 पर जाएँ
• 2:255 — सूरह 2 के आयत 255 पर जाएँ

त्वरित-संदर्भ क्वेरीज़ प्रत्येक परिणाम पर प्रासंगिकता को 'शून्य' पर सेट करके तुरंत लौटती हैं।

दर सीमाएँ

सेवा को निःशुल्क और उपलब्ध रखने के लिए, प्रत्येक क्लाइंट IP को प्रति 60 सेकंड में 10 अनुरोधों तक सीमित किया गया है।

• मानक प्रॉक्सी हेडर (`X-Forwarded-For`, `X-Real-IP`) का उपयोग करके प्रत्येक IP पते के लिए सीमाएँ ट्रैक की जाती हैं।
• सीमित होने पर, API `Retry-After` हेडर (पुनः प्रयास करने तक सेकंड) के साथ HTTP 429 लौटाता है।
• स्वचालित स्क्रैपिंग, थोक क्वेरी, या सीमाओं को दरकिनार करने के प्रयासों के परिणामस्वरूप अवरोधन हो सकता है।

{
  "ok": false,
  "error": "Too many requests. Please slow down."
}

त्रुटि प्रतिक्रियाएँ

विफल अनुरोध एक JSON बॉडी लौटाते हैं जिसमें 'ok' को 'false' पर सेट किया जाता है और एक छोटा त्रुटि संदेश होता है।

सभी त्रुटि प्रतिक्रियाएँ इस आकार का उपयोग करती हैं: 'ok': false, 'error': "message"।

कोड उदाहरण

cURL

curl -X POST 'https://openquran.app/api/ai-search' \
  -H 'Content-Type: application/json' \
  -d '{"query":"patience in hardship"}'

JavaScript

const response = await fetch('https://openquran.app/api/ai-search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'patience in hardship' }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error ?? response.statusText);
}

const data = await response.json();
console.log(data.results);

अस्वीकरण

परिणाम एक AI मॉडल द्वारा उत्पन्न किए जाते हैं और अधूरे या अपूर्ण हो सकते हैं। वे लोगों को कुरान का अन्वेषण करने में मदद करने के लिए संकेत मात्र हैं — धार्मिक निर्णय या आधिकारिक व्याख्या नहीं। हमेशा आयतों को उनके पूर्ण संदर्भ में पढ़ें।

इस API का उपयोग करके आप हमारी सेवा की शर्तें और गोपनीयता नीति से सहमत होते हैं।