API Guide

Fetch passages from the Maronite liturgical Bible (Arabic) as JSON, using a standard Bible reference in English or Arabic: the whole New Testament verse by verse, and the Old Testament readings of the lectionary.

…

Base URL

https://example.com/api/v1/ar/

• v1 is the API version. ar is the language of the text (the Arabic liturgical edition).
• All requests are GET and return JSON (UTF-8). CORS is open, so you can call it from any web page.

1. Get passages by reference

/api/v1/ar/?ref=Mat 5:3; 6:9–13
/api/v1/ar/?ref=متى ٥/٣؛ ٦/٩-١٣

URL-encode the reference (encodeURIComponent in JavaScript, rawurlencode in PHP).

Notation

Single-chapter books (Philemon, 2 John, 3 John, Jude) are cited by verse: Jude 3-5.

English or Arabic, any digits

• Books: English codes (MAT), Arabic codes (متى), and common names and abbreviations: Mt, Matt, Matthew, 1 Cor, 1 John, مرقس, لوقا, يوحنا, رسُل, أع… Case, spaces, dots and diacritics don't matter.
• Digits: 0-9 or ٠-٩, anywhere: ١قور ١٣/٤-٧.
• Chapter–verse separator: :, . or /.
• Ranges: -, – or —. Lists: ; ؛ and , ،.

Response

{
  "query": "Mat 6:9-10",
  "passages": [
    {
      "reference": "MAT 6:9-10",
      "reference_ar": "متى 6/9-10",
      "book": { "id": 47, "code": "MAT", "code_ar": "متى", "testament": "NT", "name": "إنجيل سيِّدنا يسوع المسيح كما رواه متّى" },
      "from": { "chapter": 6, "verse": 9 },
      "to":   { "chapter": 6, "verse": 10 },
      "verses": [
        { "chapter": 6, "verse": 9,  "text": "أَمَّا أَنْتُم فَصَلُّوا هكَذَا: …" },
        { "chapter": 6, "verse": 10, "text": "لِيَأْتِ مَلَكُوتُكَ، …" }
      ]
    }
  ],
  "errors": []
}

A range running past the end of a chapter stops at its last verse. Verses the edition omits (e.g. Mt 23:14) have the text ....

2. Get a passage by parameters

/api/v1/ar/?book=MAT&chapter=5                                  Matthew 5
/api/v1/ar/?book=MAT&chapter=5&verse=3&to_verse=12              Matthew 5:3-12
/api/v1/ar/?book=JHN&chapter=3&verse=16&to_chapter=4&to_verse=2  John 3:16-4:2
/api/v1/ar/?book=متى&chapter=٥                                  Matthew 5
/api/v1/ar/?book=73                                             Revelation
/api/v1/ar/?book=ISA&chapter=42&verse=1                          Isaiah 42:1-8 (an Old Testament reading)

The response is the same as above, without query.

Liturgical mode

By default the API returns the biblical text. Add mode=liturgical to a ?ref= or ?book= request to get the text as it is read in the liturgy.

/api/v1/ar/?ref=لو 13/6-9&mode=liturgical

• Which reading: a passage that starts where a liturgical reading starts uses that reading. The following parts of the same book belong to it too, so a reading in several parts (متى6/33-34، 7/1-15) works as one.
• Lectionary opening: the first verse of the query is replaced by the lectionary wording when a reading starts with it (for example قالَ الربُّ يَسوعُ… instead of وَقَالَ…) and marked "override": true. The same verse inside a passage keeps its biblical wording.
• Quotation marks: in the other verses, "…" becomes «…».
• Extra fields: each passage gets reading (id and label, or null when the passage is not a reading) and text, the whole passage with one verse per line and no verse numbers. The readings markers are left out.

{
  "query": "لو 13/6-9",
  "mode": "liturgical",
  "passages": [
    {
      "reference": "LUK 13:6-9",
      "reading": { "id": 123, "label": "لو 13/6-9" },
      "text": "قالَ الربُّ يَسوعُ هذَا المَثَل: «كَانَ لِرَجُلٍ…\nفقالَ لِلكَرَّام…",
      "verses": [
        { "chapter": 13, "verse": 6, "text": "قالَ الربُّ يَسوعُ هذَا المَثَل: «…", "override": true },
        …
      ],
      …
    }
  ],
  "errors": []
}

mode=bible (the default) returns the text unchanged. Any other value is an error.

Old Testament

The Maronite Church has no full Arabic translation of the Old Testament, only the readings of the lectionary. These readings are available, each as a whole: there is no verse-by-verse text.

/api/v1/ar/?ref=أش 42/1-8
/api/v1/ar/?ref=Isa 61:1
/api/v1/ar/?ref=يون 2                 (a chapter alone works when only one reading starts in it)

• Matching: a request returns the reading that starts at the requested chapter and verse. The whole reading is returned even if the request asks for fewer verses.
• Other passages: Old Testament text that is not the start of a reading gives an error listing the readings available for that book.
• Response: the passage has "verses": null, "source": "lectionary", the whole text in text, and reading with its id, label, title and liturgical day. mode makes no difference: the text is already the liturgical one.

{
  "query": "أش 42/1-8",
  "passages": [
    {
      "reference": "ISA 42:1-8",
      "reference_ar": "أش 42/1-8",
      "book": { "id": 29, "code": "ISA", "code_ar": "أش", "testament": "OT", "name": "سفر أشعيا" },
      "from": { "chapter": 42, "verse": 1 },
      "to":   { "chapter": 42, "verse": 8 },
      "source": "lectionary",
      "reading": { "id": 21106, "label": "…", "title": "قراءة العهد القديم في …", "day": "…" },
      "text": "هُوَذَا عَبْدِي الَّذِي أَعْضُدُهُ…",
      "verses": null
    }
  ],
  "errors": []
}

3. List the books

/api/v1/ar/?books

{
  "books": [
    {
      "id": 29, "code": "ISA", "code_ar": "أش", "testament": "OT", "name": "سفر أشعيا",
      "chapters": [],
      "readings": [ { "id": 21106, "reference": "ISA 42:1-8", "reference_ar": "أش 42/1-8", "title": "…", "day": "…" }, … ]
    },
    …
    {
      "id": 47, "code": "MAT", "code_ar": "متى", "testament": "NT", "name": "إنجيل سيِّدنا يسوع المسيح كما رواه متّى",
      "chapters": [ { "chapter": 1, "verses": 25 }, { "chapter": 2, "verses": 23 }, … ]
    },
    …
  ]
}

Books are numbered in the Catholic canonical order: 1 Genesis … 46 Malachi, 47 Matthew … 73 Revelation.

Book codes

Errors

Each part of a reference is resolved separately: valid parts come back in passages, the others are explained in errors.

Code examples

JavaScript

const res = await fetch('https://example.com/api/v1/ar/?ref=' + encodeURIComponent('يو ١٥/٩-١٧'));
const { passages, errors } = await res.json();
for (const p of passages) {
  console.log(p.reference_ar);
  for (const v of p.verses) console.log(v.verse, v.text);
}

PHP

$json = file_get_contents('https://example.com/api/v1/ar/?ref=' . rawurlencode('Mat 5:3-12'));
$data = json_decode($json, true);
foreach ($data['passages'][0]['verses'] as $v) {
    echo "{$v['verse']} {$v['text']}\n";
}

curl

curl "https://example.com/api/v1/ar/?book=MAT&chapter=5&verse=3&to_verse=12"