API Guide

Fetch passages from the Maronite liturgical New Testament (Arabic) as JSON, using a standard Bible reference in English or Arabic.

…

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.

Request	Returns
`?ref=<reference>`	Passages for a reference written in standard notation
`?book=…&chapter=…`	A passage given as separate parameters
`?books`	All books, with the number of verses in each chapter

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

Write	To get	Example
`Book C:V`	one verse	`John 3:16`
`Book C:V-V`	a range of verses	`Mat 5:3-12`
`Book C:V-C:V`	a range across chapters	`Mt 5:48-6:4`
`Book C:V, V, V-V`	several verses of one chapter	`Mk 1:1, 4-8, 14`
`Book C`	a whole chapter	`1 Cor 13`
`Book C-C`	several chapters	`Rom 5-6`
`Book`	a whole book	`Jude`
`A; B`	several passages; a part without a book continues the previous book	`Mat 5:3; 6:9-13`

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": 1, "code": "MAT", "code_ar": "متى", "name": "إنجيل سيِّدنا يسوع المسيح كما رواه متّى" },
      "from": { "chapter": 6, "verse": 9 },
      "to":   { "chapter": 6, "verse": 10 },
      "verses": [
        { "chapter": 6, "verse": 9,  "text": "أَمَّا أَنْتُم فَصَلُّوا هكَذَا: …" },
        { "chapter": 6, "verse": 10, "text": "لِيَأْتِ مَلَكُوتُكَ، …" }
      ]
    }
  ],
  "errors": []
}

Field	Meaning
`passages`	One entry per range, in the order requested
`reference` / `reference_ar`	The range in standard form, in English (`MAT 5:3-12`) and Arabic (`متى 5/3-12`)
`book`	`id` (1–27), `code`, `code_ar`, `name` as printed in the edition
`from` / `to`	First and last verse returned
`verses`	`chapter`, `verse`, `text`
`verses[].readings`	Only on verses where a liturgical reading begins, e.g. `["يو 2/1-15"]`
`errors`	Problems with parts of the reference that could not be resolved

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

Parameter	Description
`book` (required)	English code, Arabic code, abbreviation, or id (1–27)
`chapter`	Start chapter. Omit for the whole book
`verse`	Start verse. Omit for the whole chapter
`to_chapter`	End chapter. Defaults to `chapter`
`to_verse`	End verse. Defaults to `verse` if only `verse` is given, otherwise the end of the chapter

/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=27                                             Revelation

The response is the same as above, without query.

3. List the books

/api/v1/ar/?books

{
  "books": [
    {
      "id": 1, "code": "MAT", "code_ar": "متى", "name": "إنجيل سيِّدنا يسوع المسيح كما رواه متّى",
      "chapters": [ { "chapter": 1, "verses": 25 }, { "chapter": 2, "verses": 23 }, … ]
    },
    …
  ]
}

Book codes

id	code	code_ar	id	code	code_ar	id	code	code_ar

Errors

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

Example	Error
`Xyz 1:1`	`Unknown book "Xyz"`
`6:9`	`No book given for "6:9"`
`Mat 29`	`MAT has no chapter 29 (it has 28)`
`Mat 5:99`	`MAT 5 has no verse 99 (it has 48)`
`Mat 5:12-3`	`Range ends before it starts in MAT 5:12-5:3`
`Mat 5:3x`	`Cannot read "5:3x" in MAT`

HTTP status	When
`200`	At least one passage found (other parts may still have errors)
`400`	Nothing could be resolved, a parameter is invalid, or no parameters were given
`500`	The database is unavailable

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"