The Bible Brain API (also referred to as “Digital Bible Platform” or “DBP”) is a RESTful API that returns JSON formatted responses. All requests made by reader applications use the HTML GET method. All requests require a developer API key to be provided. This key is provided at the time your developer account is created.
If you already have an API key and have used it within the last year on an earlier version of DBP, the key will still be available for use on DBP4.
In order to use DBP, here are some core concepts to understand.
A single Bible Version can have multiple filesets (text, audio, video, drama, non-drama, etc). In BibleBrain, related filesets are grouped by having the same BibleId, which is usually six-characters long, and usually matches the first six characters of the related FilesetIds. There are some cases however where the characters do not match exactly, so it is NOT safe to make that assumption. So a BibleId will usually have the format LLLVVV where LLL is the language ISO 639 code and VVV identifies the Bible version.
Each Bible consists of one or more filesets. A fileset is a logical grouping of contents for a specific Bible, in a particular size, drama type, and media type. Each fileset is identified by a FilesetId. If you are familiar with the earlier version of DBP, FilesetId is functionally equivalent to DAMID’s (and most 10-character FilesetId’s exactly match the corresponding v2 DAMID, with FilesetId’s longer than 10 characters being unique to DBP v4).
The filesetid is your key to delivering Bible content. Most of the other endpoints are intended to help you answer the question: which filesetid am I looking for?
The filesetId naming convention is LLLVVV[CDMM-xxxxx], with the first six characters usually matching the BibleId and the square brackets indicating optional characters. Optional characters after the dash describe the media encoding used to produce the audio or video fileset.
For example, ENGESVN2DA would be a fileset containing
- English (ENG)
- ESV version (ESV)
- New Testament (N)
- multi-voice with background music (2)
- audio (DA), as mp3 files encoded at constant 64kbps bitrate
In general, filesets which start with the same first 6 characters are different formats of the same Bible. We offer as many fileset types as we can for each Bible, subject to license or technical limitations.
A six-character fileset is used for Bible Texts (which contain all available books across both testaments).
Note: filesetid values are purely conventional, intended to make it easier for a human to get a general idea of what content is associated with the id. DBP4 always provides additional information which exactly describes the content (eg, media type, drama/non-drama, etc.).
There are filesets that do not exactly match the convention. So unlike DBP2 DAMID, client decoding of filesetId is not necessary and is explicitly discouraged.
These full-length feature films use the actual Gospel texts as their scripts—word-for-word. Created by LUMO using extensive theological, historical, and archaeological research, each film has been adapted with Faith Comes By Hearing's audio Scripture in the languages of the world.
Each language is identified by a unique three-character language code. These language codes are intended to always match the ISO 639-3 language set, and is documented fully in SIL's Ethnologue.
Languages returned by DBP contain both a language_name and an english_name field. In many cases, these fields contain the same value, but generally, the language_name field will contain the localized name. For example, for language code “CHN”, the english_name field returns “Chinese, Mandarin”, whereas the language_name field returns “中文”.
Each version of the Bible has a unique version code. Versions are not directly related to languages, and a single version code can appear in more than one language. For instance, the King James Version (KJV) appears in both English and Thai.
Text content is returned directly in API call response payloads. Audio and Video content are stored in a Content Delivery Network, and API response payloads will return signed URLS to specific audio or video files.
When available, DBP can provide the approximate starting time for each verse. This can be helpful if you are planning to present a combination of text and audio “karaoke-style”. This information is also useful when you want to play audio in response to a keyword search.
The license allows for certain content to be downloaded for offline personal use within the application if the content is specifically marked as permitted for download within the API. The API indicates applicable content via the /download/list endpoint. This endpoint requires an API Key; any fileset from the resulting content list can be downloaded via the /download/:filesetid endpoint. Note that the content must remain within the application; the license allows the content to only be consumed by the application associated with the API Key.
We have created a series of API request examples to help you be productive more quickly. The requests are organized as Postman collections. Once you add your API key, you can submit requests directly from Postman. If you wish to download Postman, click on this link. You will also have an opportunity to download when you access the Example Workflows collection, which is located here.
To run the collection, import it into a personal workspace and configure the API key once, at the root level, under Authorization (provide snapshot or two on how to do this). The key will then be used for all requests in the collection.
To request an API key, click here and provide some basic information.
Unfortunately, Internet Explorer is an outdated browser and we do not currently support it. To have the best browsing experience, please upgrade to Microsoft Edge, Google Chrome or Safari.
