Koranens AI-sök-API

Översikt

AI-sök-API:et matchar naturligt språk-frågor med suror och verser i Koranen med hjälp av semantisk AI. Det är utformat för integratörer som vill ha temabaserad upptäckt utan att bygga sitt eget sökindex eller LLM-pipeline.

• Returnerar ett enda JSON-svar som du kan tolka med vilken HTTP-klient som helst.
• Skriver varje resultats relevansbeskrivning på det språk du anger, eller upptäcker automatiskt frågespråket (detectedLanguage) när du utelämnar det.
• Returnerar strukturerade sura- och versnummer som din app kan länka till.

Slutpunkt

Skicka en JSON-kropp med användarens sökfras. API:et svarar med ett enda JSON-objekt som innehåller de matchande referenserna.

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

Rubriker

Förfrågan

Förfrågans kropp är ett enda JSON-objekt:

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

Begränsningar

• Förfrågan måste vara 2–300 tecken efter trimning.
• language är valfritt: en ISO 639-1-kod (t.ex. en, ar, fr) för relevansförklaringarna. När det utelämnas eller är ogiltigt, upptäcks språket automatiskt från frågan.
• Maximalt 12 resultat per förfrågan.
• Inledande och avslutande blanksteg tas bort.

Svar

Framgångsrika förfrågningar returnerar HTTP 200 med ett JSON-objekt.

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"
}

Varje objekt i resultaten inkluderar ett relevansfält. Den texten är skriven på det språk du begärde, eller på det upptäckta frågespråket (detectedLanguage) när inget språk angavs — till exempel ger en arabisk fråga arabiska relevansbeskrivningar.

Fält på toppnivå

Resultattyper

Varje resultat är ett taggat objekt — antingen en hel sura eller en enskild 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 — Suranummer, 1–114.
• ayah — Versnummer baserat på 1 inom suran (endast versresultat).
• relevance — En enmeningsförklaring av varför referensen matchar, skriven på det begärda språket eller det upptäckta frågespråket. Null för snabbreferenssökningar.

Snabb referens

Bara suranummer och versreferenser hoppar över AI-modellen och löses omedelbart:

• 2 — navigera till Sura 2
• 2:255 — navigera till vers 255 i Surah 2

Snabbreferensfrågor returnerar omedelbart med relevans satt till null för varje resultat.

Hastighetsbegränsningar

För att hålla tjänsten gratis och tillgänglig är varje klient-IP begränsad till 10 förfrågningar per 60 sekunder.

• Gränser spåras per IP-adress med hjälp av standardproxy-headers (`X-Forwarded-For`, `X-Real-IP`).
• Vid begränsning returnerar API:et HTTP 429 med en `Retry-After`-header (sekunder tills du kan försöka igen).
• Automatisk skrapning, massförfrågningar eller försök att kringgå gränser kan leda till blockering.

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

Felsvar

Misslyckade förfrågningar returnerar en JSON-kropp med 'ok' satt till 'false' och ett kort felmeddelande.

Alla felsvar använder formatet: 'ok': false, 'error': "meddelande".

Kodexempel

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

Friskrivning

Resultaten genereras av en AI-modell och kan vara ofullständiga eller imperfekta. De är vägledande för att hjälpa människor att utforska Koranen – inte religiösa avgöranden eller auktoritativ tolkning. Läs alltid verser i deras fulla sammanhang.

Genom att använda denna API godkänner du våra Användarvillkor och Integritetspolicy.