قرآن 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 — ایک جملے کی وضاحت کہ حوالہ کیوں مطابقت رکھتا ہے، درخواست کردہ زبان یا پتہ لگائی گئی سوال کی زبان میں لکھا گیا۔ فوری حوالہ جات کی تلاش کے لیے Null۔

فوری حوالہ

صرف سورہ نمبر اور آیت کے حوالہ جات AI ماڈل کو نظر انداز کرتے ہیں اور فوری طور پر حل ہو جاتے ہیں:

• 2 — سورہ 2 پر جائیں
• 2:255 — سورہ 2 کی آیت 255 پر جائیں

فوری حوالہ کی استفسارات فوری طور پر واپس آتی ہیں جس میں ہر نتیجے پر مطابقت null پر سیٹ ہوتی ہے۔

شرح کی حدود

سروس کو مفت اور دستیاب رکھنے کے لیے، ہر کلائنٹ 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 کو استعمال کرکے آپ ہماری سروس کی شرائط اور رازداری کی پالیسی سے اتفاق کرتے ہیں۔