API Carian AI Quran

Gambaran Keseluruhan

API carian AI memadankan pertanyaan bahasa semula jadi dengan surah dan ayat dalam Al-Quran menggunakan AI semantik. Ia direka untuk pengintegrasi yang mahukan penemuan berasaskan tema tanpa membina indeks carian atau saluran paip LLM mereka sendiri.

• Mengembalikan satu respons JSON yang boleh anda huraikan dengan mana-mana klien HTTP.
• Menulis ringkasan relevansi setiap hasil dalam bahasa yang anda berikan, atau mengesan bahasa pertanyaan secara automatik (detectedLanguage) apabila anda tidak menyertakannya.
• Mengembalikan nombor surah dan ayat berstruktur yang boleh dipautkan oleh aplikasi anda.

Titik Akhir

Hantar badan JSON dengan frasa carian pengguna. API akan membalas dengan satu objek JSON yang mengandungi rujukan yang sepadan.

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

Pengepala

Permintaan

Badan permintaan adalah satu objek JSON:

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

Batasan

• Pertanyaan mestilah 2–300 aksara selepas pemangkasan.
• language adalah pilihan: kod ISO 639-1 (cth. en, ar, fr) untuk penjelasan relevansi. Apabila diabaikan atau tidak sah, bahasa akan dikesan secara automatik daripada pertanyaan.
• Maksimum 12 hasil setiap pertanyaan.
• Ruang kosong di hadapan dan belakang akan dibuang.

Respons

Permintaan yang berjaya mengembalikan HTTP 200 dengan objek JSON.

Jenis Kandungan: 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"
}

Setiap item dalam hasil termasuk medan relevansi. Teks tersebut ditulis dalam bahasa yang anda minta, atau dalam bahasa pertanyaan yang dikesan (detectedLanguage) apabila tiada bahasa disediakan — contohnya, pertanyaan Arab menghasilkan ringkasan relevansi Arab.

Medan peringkat atas

Jenis hasil

Setiap hasil adalah objek bertanda — sama ada surah penuh atau satu ayat:

// 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 — Nombor surah, 1–114.
• ayah — Nombor ayat berasaskan 1 dalam surah (hasil ayat sahaja).
• relevance — Penjelasan satu ayat mengapa rujukan sepadan, ditulis dalam bahasa yang diminta atau bahasa pertanyaan yang dikesan. Null untuk carian rujukan pantas.

Rujukan pantas

Nombor surah dan rujukan ayat kosong melangkau model AI dan diselesaikan serta-merta:

• 2 — navigasi ke Surah 2
• 2:255 — navigasi ke ayat 255 Surah 2

Pertanyaan rujukan pantas dikembalikan serta-merta dengan relevansi ditetapkan kepada null pada setiap hasil.

Had kadar

Untuk memastikan perkhidmatan percuma dan tersedia, setiap IP klien dihadkan kepada 10 permintaan setiap 60 saat.

• Had dijejak mengikut alamat IP menggunakan pengepala proksi standard (`X-Forwarded-For`, `X-Real-IP`).
• Apabila dihadkan, API mengembalikan HTTP 429 dengan pengepala `Retry-After` (saat sehingga anda boleh mencuba semula).
• Pengikisan automatik, pertanyaan pukal, atau percubaan untuk mengelak had boleh mengakibatkan penyekatan.

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

Respons ralat

Permintaan yang gagal mengembalikan badan JSON dengan 'ok' ditetapkan kepada 'false' dan mesej ralat ringkas.

Semua respons ralat menggunakan bentuk: 'ok': false, 'error': "message".

Contoh kod

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);

Penafian

Hasil dijana oleh model AI dan mungkin tidak lengkap atau tidak sempurna. Ia adalah petunjuk untuk membantu orang ramai meneroka Al-Quran — bukan fatwa agama atau tafsiran berwibawa. Sentiasa baca ayat-ayat dalam konteks penuhnya.

Dengan menggunakan API ini, anda bersetuju dengan Syarat Perkhidmatan dan Dasar Privasi kami.