api.bible-api

API.Bible API

Library that provides a typed interface for the Api.Bible web services API.Bible

Getting started

You must first apply for an account and submit your app to API.Bible. See docs

API Levels

There are two levels of api provided by this library. The first is the ApiBibleBaseAPI. This is the lowest level and can be used to build your own services. The second, and higher level, api is ApiBibleUtility. It can be used to perform functions such as loading an entire bible and then saving it to disk. Note that this utility class is dependent upon the lower level api.

Verse parsing

The verse data returned by the api is in an unparsed, granular, format and must be processed to be human-readable. A default parser (DefaultVerseParser) is provided that produces a format that is suitable for most uses. For example, in the KJV text, words in italics are preserved.

To provide your own parser, subclass the VerseParser class and implement the parse method. Then, provide your verse parser to the constructor of the ApiBibleUtility instance.

Terminology

Bible : Collection of books.

Book : Collection of chapters and possibly notes and summaries.

Chapter : Collection of verses and notes.

Verse : Text of bible.

Example use

ApiBibleBaseAPI

Getting basic info about a bible

Bibles have a string id

const api = new ApiBibleBaseAPI( 'your-api-key' );
const bible = await api.getBible( 'bible-id' );
console.log( bible.name )

Get books of a bible

const api = new ApiBibleBaseAPI( 'your-api-key' );
const books = await api.getBooks( 'bible-id' );

Get verses of a book and chapter

Verses are returned in an unparsed format and must be constructed.

const api = new ApiBibleBaseAPI( 'your-api-key' );
const verses = await api.getVerses( 'bible-id', 'chapter-id' );

ApiBibleUtility

Load entire bible

const utility = new ApiBibleUtility( 'your-api-key', 'bible-id' );
await utility.loadEntireBible( 'path-to-file.json' );

With custom parser

const utility = new ApiBibleUtility( 'your-api-key', 'bible-id' );
await utility.loadEntireBible( 'path-to-file.json', new MyParser() );

DefaultVerseParser

This parser reduces multiple white spaces to a single space and leaves special words and phrase that were added by the translators intact. For example, in the KJV, words that were added to clarify the text and are usually printed in italics are preserved.

Note that the verse parser can be used with verse data returned by the ApiBibleBaseAPI, without the use of the ApiBibleUtility class. This facilitates implementing your own utility class without having to create your own parser, when the default parser meets your needs.

Verse parsing has some intricacies in how the text is provided by the api. A study of the returned data and an understanding of Bible text is needed to create a custom parser.