The BibleClient class provides methods for fetching Bible data from the YouVersion Platform API. It supports retrieving Bible versions, books, chapters, verses, passages, and the Verse of the Day (VOTD).
// Get the NIV (version ID 111)const niv = await bibleClient.getVersion(111);console.log(niv.title); // "New International Version"console.log(niv.abbreviation); // "NIV"console.log(niv.language_tag); // "en"console.log(niv.books); // ["GEN", "EXO", "LEV", ...]
// Get all books in a versionconst books = await bibleClient.getBooks(111);books.data.forEach(book => { console.log(`${book.id}: ${book.title} (${book.canon})`);});
The requested Bible book, which may include an optional intro field. Use the passage_id from the intro with getPassage() to fetch introduction content.
// Get the book of Johnconst john = await bibleClient.getBook(111, 'JHN');console.log(john.title); // "John"console.log(john.full_title); // "The Gospel According to John"console.log(john.canon); // "new_testament"// Check for introductionif (john.intro) { const intro = await bibleClient.getPassage(111, john.intro.passage_id); console.log(intro.content);}
// Get all chapters in Matthewconst chapters = await bibleClient.getChapters(111, 'MAT');console.log(`Matthew has ${chapters.data.length} chapters`);chapters.data.forEach(chapter => { console.log(`Chapter ${chapter.title}: ${chapter.passage_id}`);});
// Get all verses in John 3const verses = await bibleClient.getVerses(111, 'JHN', 3);console.log(`John 3 has ${verses.data.length} verses`);// Fetch content for each versefor (const verse of verses.data) { const passage = await bibleClient.getPassage(111, verse.passage_id); console.log(`${verse.title}: ${passage.content}`);}
// Get John 3:16const verse = await bibleClient.getPassage(111, 'JHN.3.16');console.log(verse.reference); // "John 3:16"console.log(verse.content); // HTML content
// Get VOTD for day 1 (January 1)const votd = await bibleClient.getVOTD(1);console.log(`Day ${votd.day}: ${votd.passage_id}`);// Fetch the actual verse contentconst passage = await bibleClient.getPassage(111, votd.passage_id);console.log(passage.reference);console.log(passage.content);
When searching for versions, use wildcards to match all language variants:
// Match all English variants (en, en-US, en-GB, etc.)const versions = await bibleClient.getVersions('en*');// Match specific languageconst spanishVersions = await bibleClient.getVersions('es');
Fetch passages instead of individual verses
For better performance, use getPassage() to fetch multiple verses at once:
// ❌ Not recommended - multiple API callsfor (let i = 1; i <= 5; i++) { const verse = await bibleClient.getVerse(111, 'JHN', 3, i); // ...}// ✅ Recommended - single API callconst passage = await bibleClient.getPassage(111, 'JHN.3.1-5');
Cache version and book data
Version and book metadata rarely changes, so cache it to reduce API calls:
// Cache versionsconst versionsCache = new Map<string, Collection<BibleVersion>>();async function getVersionsCached(lang: string) { if (!versionsCache.has(lang)) { const versions = await bibleClient.getVersions(lang); versionsCache.set(lang, versions); } return versionsCache.get(lang)!;}
Handle pagination for large result sets
When fetching all results, handle pagination properly:
async function getAllVersions(language: string) { const allVersions: BibleVersion[] = []; let nextToken: string | null = null; do { const result = await bibleClient.getVersions(language, undefined, { page_size: 50, page_token: nextToken || undefined }); allVersions.push(...result.data); nextToken = result.next_page_token; } while (nextToken); return allVersions;}
Validate user input for USFM references
When accepting user input for passages, validate the format:
function isValidUSFM(usfm: string): boolean { // Basic validation for USFM format return /^[A-Z]{3}\.\d+(\.\d+)?(-\d+)?$/.test(usfm);}const userInput = 'JHN.3.16';if (isValidUSFM(userInput)) { const passage = await bibleClient.getPassage(111, userInput);} else { console.error('Invalid USFM format');}
