Referencias bíblicas

La query passage toma una cadena reference y la resuelve a versículos. Detrás hay dos analizadores: uno para nombres de libros en inglés y otro para nombres localizados en el idioma de la traducción. Admiten cosas ligeramente distintas, y conviene saberlo antes de depender de un formato.

Formatos admitidos

Todos los ejemplos siguientes están verificados contra el analizador.

Formato	Ejemplo	Resuelve a
Versículo individual	Juan 3:16	un versículo
Rango de versículos	Juan 3:16-18	versículos 16, 17, 18
Varios rangos	Mateo 25:31-33,46	versículos 31–33 y 46
Capítulo completo	Génesis 1	todos los versículos del capítulo
Entre capítulos	Romans 12:1,3-4 & 13:2-4	12:1, 12:3–4, 13:2–4
Nombre localizado	Mateo 28:18-20	versículos 18–20

GraphQL

query {
  passage(translation: "spa-rv1909", reference: "Juan 3:16") {
    reference
    text
    translationName
  }
}

cURL

curl https://bibleql.org/graphql \
  -H "Authorization: Bearer $BIBLEQL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { passage(translation: \"spa-rv1909\", reference: \"Juan 3:16\") { reference text translationName } }"}'

Ruby

require "bibleql"

client = BibleQL::Client.new(
  api_key: ENV.fetch("BIBLEQL_API_KEY"),
  api_url: "https://bibleql.org/graphql"
)

passage = client.passage("Juan 3:16", translation: "spa-rv1909")

puts passage.reference
puts passage.text

Node.js

import { BibleQLClient } from "bibleql-js";

const client = new BibleQLClient({
  apiKey: process.env.BIBLEQL_API_KEY!,
  apiUrl: "https://bibleql.org/graphql",
});

const passage = await client.passage("Juan 3:16", {
  translation: "spa-rv1909",
});

console.log(passage.reference, passage.text);

Response

{
  "data": {
    "passage": {
      "reference": "Juan 3:16",
      "text": "Porque de tal manera amó Dios al mundo, que ha dado á su Hijo unigénito, para que todo aquel que en él cree, no se pierda, mas tenga vida eterna.",
      "translationName": "Reina Valera 1909"
    }
  }
}

Las referencias se normalizan al salir

El campo reference de la respuesta es la forma interpretada, que no siempre es lo que enviaste:

Envías	Recibes
Romans 12:1,3-4 & 13:2-4	Romans 12:1,3-4,13:2-4
Psalm 23	Psalms 23
Juan 3:16	Juan 3:16

El separador & se convierte en coma, y los nombres de libros en inglés se canonizan: Psalm pasa a Psalms. Si necesitas devolver al usuario su texto original, guarda tu propia copia; no confíes en que reference regrese idéntico.

Se aceptan abreviaturas

Los nombres de libros en inglés se pueden abreviar, y la respuesta llega con el nombre completo:

Envías	Recibes
Jhn 3:16	John 3:16
Jn 3:16	John 3:16
Gen 1:1	Genesis 1:1
1 Jn 1:1	1 John 1:1

Esto hace que la entrada escrita por usuarios sea mucho más tolerante de lo que parece: en general no necesitas normalizar abreviaturas antes de enviarlas.

Referencias localizadas

Cuando el nombre del libro coincide con un nombre del idioma de la traducción, se encarga el analizador localizado:

query {
  passage(translation: "spa-rv1909", reference: "Mateo 28:18-20") {
    reference
    text
  }
}

Los nombres localizados se comparan sin distinguir mayúsculas, así que mateo funciona igual que Mateo.

Las referencias localizadas no pueden abarcar varios capítulos

El analizador localizado admite versículos individuales, rangos y multirrangos separados por comas, pero todo dentro de un capítulo. Romanos 12:1 & 13:2 no se resolverá. Las referencias entre capítulos solo funcionan con nombres de libros en inglés.

Para un pasaje entre capítulos en una traducción que no sea inglesa, haz una query por capítulo o usa el nombre del libro en inglés con la traducción no inglesa: el texto que recibes sigue siendo de esa traducción.

Consulta Nombres de libros localizados para descubrir los nombres que acepta una traducción.

Capítulos completos

Génesis 1 devuelve el capítulo entero. Para un capítulo largo eso es mucho texto en una sola respuesta, así que usa chapter cuando quieras los versículos como lista, y passage cuando los quieras unidos como prosa.

Cuando una referencia no se resuelve

Una referencia que no se puede interpretar devuelve un error de GraphQL, no un resultado vacío:

{ "errors": [{ "message": "Invalid reference: 'Nonexistent 1:1'" }] }

Una referencia que sí se interpreta pero apunta fuera del texto — Juan 3:999 — no es un error. Se resuelve a una lista verses vacía y un text vacío, así que comprueba si está vacía en lugar de esperar una excepción.

Consulta Errores para el conjunto completo de fallos.