API de Búsqueda del Corán con IA

Resumen

La API de búsqueda con IA relaciona consultas en lenguaje natural con suras y versículos del Corán utilizando IA semántica. Está diseñada para integradores que desean una búsqueda basada en temas sin construir su propio índice de búsqueda o pipeline de LLM.

• Devuelve una única respuesta JSON que puedes analizar con cualquier cliente HTTP.
• Escribe la descripción de relevancia de cada resultado en el idioma que proporciones, o detecta automáticamente el idioma de la consulta (detectedLanguage) si lo omites.
• Devuelve números de suras y versículos estructurados a los que tu aplicación puede enlazar.

Punto final

Envía un cuerpo JSON con la frase de búsqueda del usuario. La API responde con un único objeto JSON que contiene las referencias coincidentes.

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

Encabezados

Solicitud

El cuerpo de la solicitud es un único objeto JSON:

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

Restricciones

• La consulta debe tener entre 2 y 300 caracteres después de recortar.
• El idioma es opcional: un código ISO 639-1 (ej. en, ar, fr) para las explicaciones de relevancia. Si se omite o es inválido, el idioma se detecta automáticamente de la consulta.
• Máximo 12 resultados por consulta.
• Los espacios en blanco iniciales y finales se eliminan.

Respuesta

Las solicitudes exitosas devuelven HTTP 200 con un objeto JSON.

Tipo de contenido: 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"
}

Cada elemento en los resultados incluye un campo de relevancia. Ese texto está escrito en el idioma que solicitaste, o en el idioma de consulta detectado (detectedLanguage) cuando no se proporcionó ningún idioma; por ejemplo, una consulta en árabe produce descripciones de relevancia en árabe.

Campos de nivel superior

Tipos de resultados

Cada resultado es un objeto etiquetado — ya sea una sura completa o un solo versículo:

// 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 — Número de sura, 1–114.
• ayah — Número de versículo basado en 1 dentro de la sura (solo resultados de versículos).
• relevance — Explicación de una frase de por qué coincide la referencia, escrita en el idioma solicitado o en el idioma de consulta detectado. Nulo para búsquedas de referencia rápida.

Referencia rápida

Los números de suras y las referencias de versículos sin formato omiten el modelo de IA y se resuelven al instante:

• 2 — navegar a la Sura 2
• 2:255 — navegar al versículo 255 de la Sura 2

Las consultas de referencia rápida se devuelven inmediatamente con la relevancia establecida en nulo para cada resultado.

Límites de tasa

Para mantener el servicio gratuito y disponible, cada IP de cliente está limitada a 10 solicitudes cada 60 segundos.

• Los límites se rastrean por dirección IP utilizando encabezados de proxy estándar (`X-Forwarded-For`, `X-Real-IP`).
• Cuando se alcanza el límite, la API devuelve HTTP 429 con un encabezado `Retry-After` (segundos hasta que pueda reintentar).
• El raspado automatizado, las consultas masivas o los intentos de eludir los límites pueden resultar en un bloqueo.

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

Respuestas de error

Las solicitudes fallidas devuelven un cuerpo JSON con 'ok' establecido en falso y un mensaje de error corto.

Todas las respuestas de error utilizan la forma: 'ok': false, 'error': "mensaje".

Ejemplos de código

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

Descargo de responsabilidad

Los resultados son generados por un modelo de IA y pueden ser incompletos o imperfectos. Son indicaciones para ayudar a las personas a explorar el Corán, no dictámenes religiosos ni interpretaciones autorizadas. Lea siempre los versículos en su contexto completo.

Al usar esta API, aceptas nuestros Términos de Servicio y Política de Privacidad.