Bolls API Documentation

This documentation is called to provide available API for creating a functioning client.

Table of contents

Before fetching Bible text

Updated at: 17 February 2021.

First of all get a list of available translations and an object with their books. The translations list contain nodes with following properties:

In order to fetch books of only one translation use the nest API:

https://bolls.life/get-books/<slug:translation>/

Where translation is an abbreviation of desired translation. Example:

https://bolls.life/get-books/YLT/

The books list contains books with the next properties:

Curl code

curl --location --request GET 'https://bolls.life/static/bolls/app/views/languages.json'

Fetch a chapter

Using that data, you can form a url to fetch a chapter. You may fetch the chapter with translator commentaries or without them. The url constructor:

https://bolls.life/get-text/<slug:translation>/<int:book>/<int:chapter>/ # Without commentaries
https://bolls.life/get-chapter/<slug:translation>/<int:book>/<int:chapter>/ # With commentaries

Where <slug:translation> is a translation abbreviation like YLT or UBIO or SYNOD, and <int:book> with <int:chapter> are numbers of a book and chapter. For example by the next url you will get the eight chapter of Song of Solomon in YLT or NKJV translation:

https://bolls.life/get-text/YLT/22/8/
https://bolls.life/get-chapter/NKJV/22/8/

Curl code

curl --location --request GET 'https://bolls.life/get-text/YLT/22/8/'
curl --location --request GET 'https://bolls.life/get-chapter/NKJV/22/8/'

The result of this request will be a list of verses of that chapter, with the next fields:

NOTE! To fetch a single verse or a few verses of one or more translations use Compare versions API

To find verses by a slug or a string you need to form a url in the next manner:

https://bolls.life/<slug:translation>?search=<str:piece>&match_case=<bool:match_case>&match_whole=<bool:match_whole>

Where <slug:translation> is an abbreviation of the translation in which you want to find something. The <str:piece> is a piece of text which can be a slug or a string which you look for. It is`not case sensitive, and it can be anything on any language: .../WLC?search=שָּׁמַ֖יִם וְאֵ֥ת, .../LXX?search=ὁ θεὸς τὸν, .../UBIO?search=Небо та землю, .../CUV?search=淵 面 黑 暗.

Also at the end of search url you may add optional boolean parameters: match_case (case sensitive search) and match_whole (precise search, match whole search string). For example the next url will returm a list of verses, where "Haggi" word is found:

https://bolls.life/search/YLT/?search=haggi&match_case=false&match_whole=true

The result of this request will be a list of top 1024 found verses in the given translation, where every verse will have some several fields:

Curl code

curl --location --request GET 'https://bolls.life/search/YLT/?search=haggi&match_case=false&match_whole=true'

Get a translation

You can get a full translation in json or zip:

https://bolls.life/static/translations/<slug:translation>.json
https://bolls.life/static/translations/<slug:translation>.zip

The result will be an array of all translation verses. For example you can try the next link:

https://bolls.life/static/translations/YLT.json

The structure of nodes in this array will be like in the nodes of search query

Curl code

curl --location --request GET 'https://bolls.life/static/translations/YLT.json'

Compare versions

You can make a request for peculiar verses in peculiar translations. If you wanna see some exact verse or verses in different translation to compare them you can use this api. The request should be POST, and you should pass in the body an object with some fields. The request url -=> https://bolls.life/get-paralel-verses/, The body of the POST request must have the nest fields:

You may request different verses in different translations only of one chapter. Imba example.

window.fetch("/get-paralel-verses/", {
	method: "POST",
	cache: "no-cache",
	headers: {
		"Content-Type": "application/json"
	},
	body: JSON.stringify({
		// Here are list of translations for comparison
		translations: ['YLT', 'WEB', KJV],

		// It may be a single verse there [3], or any number of verses,
		// and if they exist they will be returned
		verses: [3, 4, 5],

		book: 43, // an id of the book
		chapter: 1, // number of chapter
	}),
})
.then(do |response| response.json())
.then(do |resdata|
	translations_with_verses = resdata
	console.log console.log
)

The result of this request will be an array of translations where every translation is an array of requested verses, where every verse has these fields. Here is the example of the result:

[
  [
    {
      "pk": 1145257,
      "translation": "WLCC",
      "book": 18,
      "chapter": 2,
      "verse": 1,
      "text": "ויהי היום ויבאו בני האלהים להתיצב על־יהוה ויבוא גם־השטן בתכם להתיצב על־יהוה׃"
    },
    {
      "pk": 1145258,
      "translation": "WLCC",
      "book": 18,
      "chapter": 2,
      "verse": 2,
      "text": "ויאמר יהוה אל־השטן אי מזה תבא ויען השטן את־יהוה ויאמר משט בארץ ומהתהלך בה׃"
    },
    {
      "pk": 1145259,
      "translation": "WLCC",
      "book": 18,
      "chapter": 2,
      "verse": 3,
      "text": "ויאמר יהוה אל־השטן השמת לבך אל־עבדי איוב כי אין כמהו בארץ איש תם וישר ירא אלהים וסר מרע ועדנו מחזיק בתמתו ותסיתני בו לבלעו חנם׃"
    }
  ],
  [
    {
      "pk": 36107,
      "translation": "YLT",
      "book": 18,
      "chapter": 2,
      "verse": 1,
      "text": "And the day is, that sons of God come in to station themselves by Jehovah, and there doth come also the Adversary in their midst to station himself by Jehovah."
    },
    {
      "pk": 36108,
      "translation": "YLT",
      "book": 18,
      "chapter": 2,
      "verse": 2,
      "text": "And Jehovah saith unto the Adversary, 'Whence camest thou?' And the Adversary answereth Jehovah and saith, 'From going to and fro in the land, and from walking up and down in it.'"
    },
    {
      "pk": 36109,
      "translation": "YLT",
      "book": 18,
      "chapter": 2,
      "verse": 3,
      "text": "And Jehovah saith unto the Adversary, 'Hast thou set thy heart unto My servant Job because there is none like him in the land, a man perfect and upright, fearing God and turning aside from evil? and still he is keeping hold on his integrity, and thou dost move Me against him to swallow him up for nought!'"
    }
  ]
]

Fetch a verse(s)

You may need this a lot. To fetch a single verse of a few verses of a single translation you should use the compare API as I mantion it above. Just pass the translation code as array with single item, chapter number, book code and array with verse / verses and you will get it.

Imba example.

window.fetch("/get-paralel-verses/", {
	method: "POST",
	cache: "no-cache",
	headers: {
		"Content-Type": "application/json"
	},
	body: JSON.stringify({
		// Here show what translation should it be. You may add there a few translations
		translations: ['YLT'],

		// It may be a single verse there [3], or any number of verses,
		// and if they exist they will be returned
		verses: [3, 4, 5],

		book: 43, // an id of the book
		chapter: 1, // number of chapter
	}),
})
.then(do |response| response.json())
.then(do |resdata|
	translations_with_verses = resdata
	console.log(resdata)
)

Curl code

curl --location --request POST 'https://bolls.life/get-paralel-verses/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "translations": "[\"ESV\"]",
    "verses": "[1]",
    "book": 9,
    "chapter": 4
}'

Here is example of the response. YLT translation, Job (18) 2:6

[
  [
    {
      "pk": 36112,
      "translation": "YLT",
      "book": 18,
      "chapter": 2,
      "verse": 6,
      "text": "And Jehovah saith unto the Adversary, 'Lo, he [is] in thy hand; only his life take care of.'"
    }
  ]
]

As you see it is the same as Compare translation API. More detailes about the fields of this request see the Compare translation API.

Dictionary definition for Hebrew and Greek words

New from 23 December 2021.

This API is used to get a list of definitions for a Hebrew or Greek word, if such do exist in a dictionary. If there are no definitions for requested query -- an empty array is returned. The API looks in the next way:

https://bolls.life/dictionary-definition/<slug:dict>/<str:query>/

Where: dict is an abbreviation of dictionary that should be used. At this moment there are available only to dictionaries: BDBT - Brown-Driver-Briggs' Hebrew Definitions / Thayer's Greek Definitions and RUSD - Полный лексикон по Стронгу и Дворецкому, 2019 (https://bolls.life/static/bolls/app/views/dictionaries.json). query is a string -- anything in Greek or Hebrew. You may also search for English/Russian words and it will return some relative Hebrew/Greek words and their definitions. query also may be a strong number like H125 or G523 - it will return a particular definition under that Strong number. In result you will get a JSON array - empty or with definitions XD. For example the next request will return an array of definitions for the Hebrew word אֹ֑ור (light):

https://bolls.life/dictionary-definition/BDBT/אֹ֑ור

Result:

[
  {
    "topic": "H215",
    "definition": "Original: <b><he>אור</he></b> <p />Transliteration: <b>ôr</b> <p />Phonetic: <b>ore</b> <p class=\"bdb_def\"><b>BDB Definition</b>:</p><ol><li>to be or become light, shine<ol type=a><li>(Qal)<ol><li>to become light (day)</li><li>to shine (of the sun)</li><li>to become bright</li></ol><li>(Niphal)<ol><li>to be illuminated</li><li>to become lighted up</li></ol><li>(Hiphil)<ol><li>to give light, shine (of sun, moon, and stars)</li><li>to illumine, light up, cause to shine, shine</li><li>to kindle, light (candle, wood)</li><li>lighten (of the eyes, his law, etc)</li><li>to make shine (of the face)</li></ol></li></ol></li></ol> <p />Origin: a primitive root <p />TWOT entry: <a class=\"T\" href=\"S:0052 - or\">52</a> <p />Part(s) of speech: Verb ",
    "lexeme": "אֹור",
    "transliteration": "ʼôwr",
    "pronunciation": "ore",
    "short_definition": "[idiom] break of day",
    "weight": 1
  },
  {
    "topic": "H216",
    "definition": "Original: <b><he>אור</he></b> <p />Transliteration: <b>ôr</b> <p />Phonetic: <b>ore</b> <p class=\"bdb_def\"><b>BDB Definition</b>:</p><ol><li>light<ol type=a><li>light of day</li><li>light of heavenly luminaries (moon, sun, stars)</li><li>day-break, dawn, morning light</li><li>daylight</li><li>lightning</li><li>light of lamp</li><li>light of life</li><li>light of prosperity</li><li>light of instruction</li><li>light of face (figuratively)</li><li>Jehovah as Israels light</li></ol></li></ol> <p />Origin: from <a href=S:H215>H215</a> <p />TWOT entry: <a class=\"T\" href=\"S:0052 - or\">52a</a> <p />Part(s) of speech: Noun Feminine ",
    "lexeme": "אֹור",
    "transliteration": "ʼôwr",
    "pronunciation": "ore",
    "short_definition": "bright",
    "weight": 1
  },
  {
    "topic": "H217",
    "definition": "Original: <b><he>אוּר</he></b> <p />Transliteration: <b>ûr</b> <p />Phonetic: <b>ore</b> <p class=\"bdb_def\"><b>BDB Definition</b>:</p><ol><li>flame, light of fire</li></ol> <p />Origin: from <a href=S:H215>H215</a> <p />TWOT entry: <a class=\"T\" href=\"S:0052 - or\">52d</a> <p />Part(s) of speech: Noun Masculine ",
    "lexeme": "אוּר",
    "transliteration": "ʼûwr",
    "pronunciation": "ore",
    "short_definition": "fire",
    "weight": 1
  },
  {
    "topic": "H218",
    "definition": "Original: <b><he>אוּר</he></b> <p />Transliteration: <b>ûr</b> <p />Phonetic: <b>oor</b> <p class=\"bdb_def\"><b>BDB Definition</b>:</p> Ur = \"flame\" <ol><li>city in southern Babylonia, city of the Chaldeans, centre of moon worship, home of Abrahams father, Terah, and departure point for the Abrahams migration to Mesopotamia and Canaan</li></ol> <p />Origin: the same as <a href=S:H217>H217</a> <p />TWOT entry: None <p />Part(s) of speech: Proper Name Location ",
    "lexeme": "אוּר",
    "transliteration": "ʼÛwr",
    "pronunciation": "oor",
    "short_definition": "Ur",
    "weight": 1
  }
]
	

Every definition contains next fields:

Notes