API Pencarian AI Quran

Ikhtisar

API pencarian AI mencocokkan kueri bahasa alami dengan surah dan ayat dalam Al-Quran menggunakan AI semantik. Ini dirancang untuk integrator yang menginginkan penemuan berbasis tema tanpa membangun indeks pencarian atau pipeline LLM mereka sendiri.

• Mengembalikan satu respons JSON yang dapat Anda uraikan dengan klien HTTP apa pun.
• Menulis ringkasan relevansi setiap hasil dalam bahasa yang Anda berikan, atau mendeteksi bahasa kueri secara otomatis (detectedLanguage) ketika Anda tidak menyertakannya.
• Mengembalikan nomor surah dan ayat terstruktur yang dapat ditautkan oleh aplikasi Anda.

Endpoint

Kirim badan JSON dengan frasa pencarian pengguna. API merespons dengan satu objek JSON yang berisi referensi yang cocok.

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

Header

Permintaan

Isi permintaan adalah objek JSON tunggal:

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

Batasan

• Kueri harus 2–300 karakter setelah dipangkas.
• bahasa bersifat opsional: kode ISO 639-1 (misalnya en, ar, fr) untuk penjelasan relevansi. Ketika dihilangkan atau tidak valid, bahasa akan dideteksi secara otomatis dari kueri.
• Maksimal 12 hasil per kueri.
• Spasi di awal dan akhir dihilangkan.

Respons

Permintaan yang berhasil mengembalikan HTTP 200 dengan objek JSON.

Tipe Konten: 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 menyertakan bidang relevansi. Teks tersebut ditulis dalam bahasa yang Anda minta, atau dalam bahasa kueri yang terdeteksi (detectedLanguage) ketika tidak ada bahasa yang disediakan — misalnya, kueri bahasa Arab menghasilkan ringkasan relevansi bahasa Arab.

Bidang tingkat atas

Tipe hasil

Setiap hasil adalah objek berlabel — baik surah utuh 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 — Nomor surah, 1–114.
• ayah — Nomor ayat berbasis 1 dalam surah (hanya hasil ayat).
• relevance — Penjelasan satu kalimat mengapa referensi cocok, ditulis dalam bahasa yang diminta atau bahasa kueri yang terdeteksi. Null untuk pencarian referensi cepat.

Referensi cepat

Nomor surah dan referensi ayat saja akan melewati model AI dan langsung diselesaikan:

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

Kueri referensi cepat segera mengembalikan hasil dengan relevansi diatur ke null pada setiap hasil.

Batas laju

Untuk menjaga layanan tetap gratis dan tersedia, setiap IP klien dibatasi hingga 10 permintaan per 60 detik.

• Batasan dilacak per alamat IP menggunakan header proxy standar (`X-Forwarded-For`, `X-Real-IP`).
• Ketika dibatasi, API mengembalikan HTTP 429 dengan header `Retry-After` (detik hingga Anda dapat mencoba lagi).
• Pengambilan data otomatis, kueri massal, atau upaya untuk menghindari batasan dapat mengakibatkan pemblokiran.

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

Respons kesalahan

Permintaan yang gagal mengembalikan badan JSON dengan 'ok' diatur ke 'false' dan pesan kesalahan singkat.

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

Contoh kode

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 dihasilkan oleh model AI dan mungkin tidak lengkap atau tidak sempurna. Ini adalah petunjuk untuk membantu orang menjelajahi Al-Quran — bukan fatwa agama atau tafsir otoritatif. Selalu baca ayat-ayat dalam konteks lengkapnya.

Dengan menggunakan API ini, Anda menyetujui Ketentuan Layanan dan Kebijakan Privasi kami.