واجهة برمجة تطبيقات بحث القرآن بالذكاء الاصطناعي

نظرة عامة

تطابق واجهة برمجة تطبيقات البحث بالذكاء الاصطناعي الاستعلامات باللغة الطبيعية مع السور والآيات في القرآن باستخدام الذكاء الاصطناعي الدلالي. وهي مصممة للمطورين الذين يرغبون في الاكتشاف القائم على الموضوع دون بناء فهرس بحث خاص بهم أو مسار 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) لعمليات البحث السريع عن المراجع.

مرجع سريع

أرقام السور ومراجع الآيات المجردة تتجاوز نموذج الذكاء الاصطناعي وتُحل فورًا:

• 2 — انتقل إلى سورة 2
• 2:255 — الانتقال إلى الآية 255 من سورة 2

تعود استعلامات المرجع السريع فورًا مع تعيين الصلة إلى null لكل نتيجة.

حدود المعدل

للحفاظ على الخدمة مجانية ومتاحة، يقتصر كل عنوان IP للعميل على 10 طلبًا كل 60 ثانية.

• يتم تتبع القيود لكل عنوان IP باستخدام رؤوس الوكيل القياسية (`X-Forwarded-For`, `X-Real-IP`).
• عند تجاوز الحد، تُرجع واجهة برمجة التطبيقات 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، فإنك توافق على شروط الخدمة و سياسة الخصوصية الخاصة بنا.