Koran KI-Such-API

Übersicht

Die KI-Such-API gleicht natürliche Sprachanfragen mit Suren und Versen im Koran mithilfe semantischer KI ab. Sie wurde für Integratoren entwickelt, die eine themenbasierte Entdeckung wünschen, ohne ihren eigenen Suchindex oder ihre eigene LLM-Pipeline aufbauen zu müssen.

• Gibt eine einzelne JSON-Antwort zurück, die Sie mit jedem HTTP-Client parsen können.
• Schreibt die Relevanzbeschreibung jedes Ergebnisses in der von Ihnen übergebenen Sprache oder erkennt die Abfragesprache (detectedLanguage) automatisch, wenn Sie sie weglassen.
• Gibt strukturierte Suren- und Versnummern zurück, auf die Ihre App verlinken kann.

Endpunkt

Senden Sie einen JSON-Body mit der Suchphrase des Benutzers. Die API antwortet mit einem einzelnen JSON-Objekt, das die übereinstimmenden Referenzen enthält.

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

Header

Anfrage

Der Anfragekörper ist ein einzelnes JSON-Objekt:

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

Einschränkungen

• Die Abfrage muss nach dem Kürzen 2–300 Zeichen lang sein.
• Sprache ist optional: ein ISO 639-1 Code (z.B. en, ar, fr) für die Relevanzerklärungen. Wenn weggelassen oder ungültig, wird die Sprache automatisch aus der Abfrage erkannt.
• Maximal 12 Ergebnisse pro Abfrage.
• Führende und nachfolgende Leerzeichen werden entfernt.

Antwort

Erfolgreiche Anfragen geben HTTP 200 mit einem JSON-Objekt zurück.

Content-Type: 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"
}

Jedes Element in den Ergebnissen enthält ein Relevanzfeld. Dieser Text ist in der von Ihnen angefragten Sprache verfasst oder in der erkannten Abfragesprache (detectedLanguage), wenn keine Sprache angegeben wurde — zum Beispiel führt eine arabische Abfrage zu arabischen Relevanzbeschreibungen.

Felder der obersten Ebene

Ergebnistypen

Jedes Ergebnis ist ein getaggtes Objekt – entweder eine ganze Sure oder ein einzelner Vers:

// 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-Nummer, 1–114.
• ayah — 1-basierte Versnummer innerhalb der Sure (nur Versergebnisse).
• relevance — Eine einzeilige Erklärung, warum die Referenz übereinstimmt, verfasst in der angefragten Sprache oder der erkannten Abfragesprache. Null für Schnellreferenz-Suchen.

Kurzübersicht

Reine Surennummern und Versreferenzen umgehen das KI-Modell und werden sofort aufgelöst:

• 2 — navigieren Sie zu Sure 2
• 2:255 — navigiere zu Vers 255 von Sure 2

Schnellreferenz-Abfragen werden sofort zurückgegeben, wobei die Relevanz für jedes Ergebnis auf null gesetzt ist.

Ratenbegrenzungen

Um den Dienst kostenlos und verfügbar zu halten, ist jede Client-IP auf 10 Anfragen pro 60 Sekunden begrenzt.

• Limits werden pro IP-Adresse unter Verwendung standardmäßiger Proxy-Header (`X-Forwarded-For`, `X-Real-IP`) verfolgt.
• Bei Überschreitung des Limits gibt die API HTTP 429 mit einem `Retry-After`-Header zurück (Sekunden bis zum erneuten Versuch).
• Automatisiertes Scraping, Massenabfragen oder Versuche, die Limits zu umgehen, können zu einer Sperrung führen.

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

Fehlerantworten

Fehlgeschlagene Anfragen geben einen JSON-Body zurück, bei dem 'ok' auf 'false' gesetzt ist und eine kurze Fehlermeldung enthalten ist.

Alle Fehlerantworten verwenden die Form: 'ok': false, 'error': "message".

Code-Beispiele

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

Haftungsausschluss

Die Ergebnisse werden von einem KI-Modell generiert und können unvollständig oder fehlerhaft sein. Sie dienen als Hinweise, um Menschen bei der Erkundung des Korans zu helfen – nicht als religiöse Urteile oder maßgebliche Interpretationen. Lesen Sie Verse immer im vollständigen Kontext.

Durch die Nutzung dieser API stimmen Sie unseren Nutzungsbedingungen und unserer Datenschutzerklärung zu.