Kuran Yapay Zeka Arama API'si

Genel bakış

Yapay zeka arama API'si, semantik yapay zeka kullanarak doğal dil sorgularını Kuran'daki sureler ve ayetlerle eşleştirir. Kendi arama dizinlerini veya LLM boru hattını oluşturmadan tema tabanlı keşif yapmak isteyen entegratörler için tasarlanmıştır.

• Herhangi bir HTTP istemcisiyle ayrıştırabileceğiniz tek bir JSON yanıtı döndürür.
• Her sonucun alaka düzeyini, belirttiğiniz dilde yazar veya belirtmediğinizde sorgu dilini (detectedLanguage) otomatik olarak algılar.
• Uygulamanızın bağlantı verebileceği yapılandırılmış sure ve ayet numaralarını döndürür.

Uç Nokta

Kullanıcının arama ifadesini içeren bir JSON gövdesi gönderin. API, eşleşen referansları içeren tek bir JSON nesnesiyle yanıt verir.

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

Başlıklar

İstek

İstek gövdesi tek bir JSON nesnesidir:

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

Kısıtlamalar

• Sorgu, boşluklar temizlendikten sonra 2–300 karakter uzunluğunda olmalıdır.
• dil isteğe bağlıdır: alaka düzeyi açıklamaları için bir ISO 639-1 kodu (örn. en, ar, fr). Atlandığında veya geçersiz olduğunda, dil sorgudan otomatik olarak algılanır.
• Sorgu başına en fazla 12 sonuç.
• Baştaki ve sondaki boşluklar kaldırılır.

Yanıt

Başarılı istekler, bir JSON nesnesiyle HTTP 200 döndürür.

İçerik Türü: 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"
}

Sonuçlardaki her öğe bir alaka düzeyi alanı içerir. Bu metin, talep ettiğiniz dilde veya dil belirtilmediğinde algılanan sorgu dilinde (detectedLanguage) yazılır — örneğin, Arapça bir sorgu Arapça alaka düzeyi açıklamaları üretir.

Üst düzey alanlar

Sonuç türleri

Her sonuç etiketli bir nesnedir — ya tam bir sure ya da tek bir ayet:

// 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 — Sure numarası, 1–114.
• ayah — Sure içindeki 1'den başlayan ayet numarası (yalnızca ayet sonuçları için).
• relevance — Referansın neden eşleştiğine dair tek cümlelik açıklama, istenen dilde veya algılanan sorgu dilinde yazılır. Hızlı referans aramaları için null.

Hızlı başvuru

Sadece sure numaraları ve ayet referansları yapay zeka modelini atlar ve anında çözümlenir:

• 2 — 2. Sure'ye git
• 2:255 — 2. Sure'nin 255. ayetine git

Hızlı başvuru sorguları, her sonuçta alaka düzeyi null olarak ayarlanmış şekilde anında döner.

Oran limitleri

Hizmeti ücretsiz ve erişilebilir tutmak için, her istemci IP'si 60 saniyede bir 10 istekle sınırlıdır.

• Limitler, standart proxy başlıkları (`X-Forwarded-For`, `X-Real-IP`) kullanılarak IP adresine göre izlenir.
• Limit aşıldığında, API bir `Retry-After` başlığı (tekrar denemenize kadar geçen saniye) ile HTTP 429 döndürür.
• Otomatik kazıma, toplu sorgulama veya limitleri aşma girişimleri engellemeyle sonuçlanabilir.

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

Hata yanıtları

Başarısız istekler, 'ok' değeri 'false' olarak ayarlanmış ve kısa bir hata mesajı içeren bir JSON gövdesi döndürür.

Tüm hata yanıtları şu yapıyı kullanır: 'ok': false, 'error': "mesaj".

Kod örnekleri

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

Yasal Uyarı

Sonuçlar bir yapay zeka modeli tarafından üretilir ve eksik veya kusurlu olabilir. Bunlar, insanların Kuran'ı keşfetmelerine yardımcı olacak işaretlerdir; dini hükümler veya yetkili yorumlar değildir. Ayetleri her zaman tam bağlamında okuyun.

Bu API'yi kullanarak Hizmet Şartlarımızı ve Gizlilik Politikamızı kabul etmiş olursunuz.