Quran API (Edge) — مرجع المزوّد

العربية · English

• المعرّف: quran_api_edge · ملف المُحوّل: src/adapters/quran-api-edge.ts
• الصفحة الرئيسية: https://quranapi.pages.dev
• المحتوى: نصّ، صوت · الاعتماد: لا شيء · يحتاج وسيطًا: لا

ما هذا المزوّد

واجهةٌ ثابتةٌ سريعة تُقدَّم من حافة الشبكة (Edge)، وتُرجِع للآية الواحدة نصَّها وصوتها معًا في ملفّ JSON واحد. مناسبةٌ حين يهمّك زمنُ الاستجابة.

نقاط النهاية المستعملة

الرابط الأساس: https://quranapi.pages.dev/api

• النصّ والصوت (آية): GET /{surah}/{ayah}.json — ملفٌّ واحدٌ يحمل الاثنين.

بنية الاستجابة الخام

{
  "surahNo": 1,
  "ayahNo": 1,
  "arabic1": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
  "english": "In the name of Allah...",
  "surahNameArabic": "الفاتحة",
  "audio": {
    "1": {
      "reciter": "Mishary Rashid Al-Afasy",
      "url": "https://the-quran-project.github.io/Quran-Audio/Data/1/1.mp3",
      "originalUrl": "https://..."
    }
  }
}

audio كائنٌ مفتاحُه معرّفٌ رقميٌّ للقارئ.

التحويل إلى البنية الموحّدة (والسبب)

النصّ → UnifiedVerse:

الحقل الموحّد	المصدر الخام	ملاحظة
key	`${surahNo}:${ayahNo}`	مفتاح سورة:آية
id	ayahNo	رقم الآية في السورة
text	arabic1	النصّ العربي
source	"Quran API (Edge)"	ثابت
meta.surah / meta.english	surahNameArabic / english	إضافات

الصوت → UnifiedAudio: يختار المُحوّل قارئًا (المطلوب بالمعرّف، وإلا أوّل مفتاح في audio)، فيأخذ url وreciter منه، وscope = ayah، ويحفظ reciterId وoriginalUrl في meta.

نستعمل arabic1 للنصّ الأساس؛ وarabic2 (إن وُجد) صيغةٌ بديلة تُترك في meta عند الحاجة.

الاعتماد

لا يلزم.

حدود المعدّل والخصوصيات

توصيلٌ من الحافة سريع. الردّ يجمع النصّ والصوت، فيمكن خدمة نوعين من محتوى الآية بنداءٍ واحد. مفاتيح القرّاء أرقام؛ إن لم يُحدَّد قارئ أخذنا الأول.

إبقاء هذه الصفحة محدّثة

قبل تعديل المُحوّل، راجِع الواجهة الحيّة وحدِّث العيّنة في test/fixtures/quran_api_edge/. فحصُ الانحراف عبر pnpm test:live.