API de recherche coranique par IA

Aperçu

L'API de recherche IA fait correspondre les requêtes en langage naturel aux sourates et aux versets du Coran en utilisant l'IA sémantique. Elle est conçue pour les intégrateurs qui souhaitent une découverte basée sur des thèmes sans construire leur propre index de recherche ou pipeline LLM.

• Renvoie une seule réponse JSON que vous pouvez analyser avec n'importe quel client HTTP.
• Rédige le résumé de pertinence de chaque résultat dans la langue que vous spécifiez, ou détecte automatiquement la langue de la requête (detectedLanguage) si vous l'omettez.
• Renvoie des numéros de sourates et de versets structurés vers lesquels votre application peut créer des liens.

Endpoint

Envoyez un corps JSON contenant la phrase de recherche de l'utilisateur. L'API répond avec un seul objet JSON contenant les références correspondantes.

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

En-têtes

Requête

Le corps de la requête est un objet JSON unique :

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

Contraintes

• La requête doit contenir entre 2 et 300 caractères après suppression des espaces.
• language est facultatif : un code ISO 639-1 (ex. en, ar, fr) pour les explications de pertinence. S'il est omis ou invalide, la langue est automatiquement détectée à partir de la requête.
• Au maximum 12 résultats par requête.
• Les espaces de début et de fin sont supprimés.

Réponse

Les requêtes réussies renvoient HTTP 200 avec un objet JSON.

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

Chaque élément des résultats inclut un champ de pertinence. Ce texte est rédigé dans la langue que vous avez demandée, ou dans la langue de requête détectée (detectedLanguage) si aucune langue n'a été fournie — par exemple, une requête en arabe produit des résumés de pertinence en arabe.

Champs de niveau supérieur

Types de résultats

Chaque résultat est un objet étiqueté — soit une sourate entière, soit un seul verset :

// 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 — Numéro de sourate, 1–114.
• ayah — Numéro de verset basé sur 1 dans la sourate (résultats de versets uniquement).
• relevance — Explication en une phrase de la raison pour laquelle la référence correspond, rédigée dans la langue demandée ou la langue de requête détectée. Nul pour les recherches de référence rapide.

Référence rapide

Les numéros de sourates et les références de versets bruts contournent le modèle d'IA et se résolvent instantanément :

• 2 — naviguer vers la Sourate 2
• 2:255 — naviguer au verset 255 de la sourate 2

Les requêtes de référence rapide sont renvoyées immédiatement avec la pertinence définie sur null pour chaque résultat.

Limites de débit

Pour maintenir le service gratuit et disponible, chaque adresse IP client est limitée à 10 requêtes toutes les 60 secondes.

• Les limites sont suivies par adresse IP en utilisant les en-têtes de proxy standard (`X-Forwarded-For`, `X-Real-IP`).
• En cas de limitation, l'API renvoie HTTP 429 avec un en-tête `Retry-After` (secondes avant de pouvoir réessayer).
• Le scraping automatisé, les requêtes en masse ou les tentatives de contournement des limites peuvent entraîner un blocage.

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

Réponses d'erreur

Les requêtes échouées renvoient un corps JSON avec 'ok' défini sur 'false' et un court message d'erreur.

Toutes les réponses d'erreur utilisent la forme : 'ok': false, 'error': "message".

Exemples de code

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

Avertissement

Les résultats sont générés par un modèle d'IA et peuvent être incomplets ou imparfaits. Ce sont des indications pour aider les gens à explorer le Coran — et non des décisions religieuses ou une interprétation faisant autorité. Lisez toujours les versets dans leur contexte complet.

En utilisant cette API, vous acceptez nos Conditions d'utilisation et notre Politique de confidentialité.