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 — شماره سوره، ۱ تا ۱۱۴.
• ayah — شماره آیه (بر اساس ۱) در سوره (فقط نتایج آیه).
• relevance — توضیح یک جمله‌ای در مورد دلیل مطابقت مرجع، که به زبان درخواستی یا زبان جستجوی تشخیص داده شده نوشته شده است. برای جستجوهای مرجع سریع، null است.

مرجع سریع

شماره‌های سوره و مراجع آیه به تنهایی مدل AI را دور می‌زنند و فوراً حل می‌شوند:

• 2 — رفتن به سوره 2
• 2:255 — رفتن به آیه ۲۵۵ از سوره ۲

پرس‌وجوهای مرجع سریع بلافاصله با ارتباط (relevance) null برای هر نتیجه برمی‌گردند.

محدودیت‌های نرخ

برای رایگان و در دسترس نگه داشتن سرویس، هر IP کلاینت به 10 درخواست در هر 60 ثانیه محدود شده است.

• محدودیت‌ها برای هر آدرس IP با استفاده از هدرهای پراکسی استاندارد (`X-Forwarded-For`, `X-Real-IP`) ردیابی می‌شوند.
• هنگام محدود شدن، API کد HTTP 429 را با هدر `Retry-After` (ثانیه‌ها تا زمان تلاش مجدد) برمی‌گرداند.
• خراشیدن خودکار (اسکرپینگ)، پرس‌وجوهای انبوه، یا تلاش برای دور زدن محدودیت‌ها ممکن است منجر به مسدود شدن شود.

{
  "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، شما با شرایط خدمات و سیاست حفظ حریم خصوصی ما موافقت می‌کنید.