SDKs

JavaScript SDK

Copy page

The JavaScript SDK (@youversion/platform-core) provides typed API clients for fetching Bible data in any JavaScript environment.

Getting Started

Fetch and display a Bible verse.

1. Get Your App Key

Sign up at platform.youversion.com to get your free App Key.

2. Install

Code
 
npm install @youversion/platform-core

3. Fetch a Verse

Code
 
import { ApiClient, BibleClient } from '@youversion/platform-core'

const apiClient = new ApiClient({
  appKey: "YOUR_APP_KEY"
})

const bibleClient = new BibleClient(apiClient)

// Fetch John 3:16
const passage = await bibleClient.getPassage(111, 'JHN.3.16')
console.log(passage.content) // "<p>For God so loved the world...</p>"

4. Display with Copyright

Code
 
const version = await bibleClient.getVersion(111)

// In your HTML
document.innerHTML = `
  <div>${passage.content}</div>
  <p class="copyright">${version.copyright_short}</p>
`

Installation

Install the package with your preferred package manager:

Code
 
npm install @youversion/platform-core

Code
 
yarn add @youversion/platform-core

Code
 
pnpm add @youversion/platform-core

Configuration

Create an API client with your App Key:

Code
 
import { ApiClient, BibleClient } from '@youversion/platform-core'

const apiClient = new ApiClient({
  appKey: "YOUR_APP_KEY",
})

const bibleClient = new BibleClient(apiClient)

Types
 
type ApiClientOptions = {
  /**
   * Your App Key for API authentication
   * Get from https://platform.youversion.com/
   */
  appKey: string;

  /**
   * Base URL for the API
   * @default "https://api.youversion.com"
   */
  baseUrl?: string;

  /**
   * Request timeout in milliseconds
   * @default 10_000
   */
  timeout?: number;
}

BibleClient API

The BibleClient provides methods for fetching Bible versions, books, chapters, verses, and passages.

Version Methods

getVersions(language_ranges, license_id?)

Fetch available Bible versions filtered by language.

Code
 
// Get all English versions
const englishVersions = await bibleClient.getVersions('en*')

// Get multiple languages
const multiLangVersions = await bibleClient.getVersions('en*,es*,fr*')

// Filter by license
const licenseVersions = await bibleClient.getVersions('en*', 123)

Parameters:

• language_ranges (string): Comma-separated language codes or ranges (e.g., "en*", "es-ES")
• license_id (string | number, optional): License ID to filter versions

Response:

Code
 
{
  data: [
    {
      id: 1,
      abbreviation: "KJV",
      title: "King James Version",
      language_tag: "en",
      copyright_short: "...",
      books: ["GEN", "EXO", ...]
    }
  ]
}

getVersion(id)

Fetch a specific Bible version by ID.

Code
 
const niv = await bibleClient.getVersion(111)
console.log(niv.title) // "New International Version"

Parameters:

• id (number): Bible version ID

Troubleshooting: If you get a "Version not found" error (404), verify the version ID exists:

Code
 
const versions = await bibleClient.getVersions('en*')
const validIds = versions.data.map(v => v.id)
console.log('Valid version IDs:', validIds)

Book Methods

getBooks(versionId)

Fetch all books for a specific Bible version.

Code
 
const books = await bibleClient.getBooks(111)

Parameters:

• versionId (number): Bible version ID

Response:

Code
 
{
  data: [
    {
      id: "GEN",
      title: "Genesis",
      abbreviation: "Gen",
      canon: "ot",
      chapters: ["1", "2", "3", ...]
    }
  ]
}

getBook(versionId, book)

Fetch a specific book by its USFM identifier.

Code
 
const genesis = await bibleClient.getBook(111, 'GEN')
console.log(genesis.title) // "Genesis"
console.log(genesis.chapters.length) // 50

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code (e.g., "GEN", "MAT", "JHN")

Chapter Methods

getChapters(versionId, book)

Fetch all chapters for a specific book.

Code
 
const chapters = await bibleClient.getChapters(111, 'GEN')
console.log(chapters.data.length) // 50

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code

getChapter(versionId, book, chapter)

Fetch a specific chapter.

Code
 
const genesis1 = await bibleClient.getChapter(111, 'GEN', 1)
console.log(genesis1.title) // "Genesis 1"

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code
• chapter (number): Chapter number

Verse Methods

getVerses(versionId, book, chapter)

Fetch all verses for a specific chapter.

Code
 
const verses = await bibleClient.getVerses(111, 'GEN', 1)
console.log(verses.data.length) // 31

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code
• chapter (number): Chapter number

Response:

Code
 
{
  data: [
    {
      id: "GEN.1.1",
      book_id: "GEN",
      chapter_id: "1",
      passage_id: "GEN.1.1",
      reference: "Genesis 1:1"
    }
  ]
}

getVerse(versionId, book, chapter, verse)

Fetch a specific verse.

Code
 
const verse = await bibleClient.getVerse(111, 'GEN', 1, 1)
console.log(verse.reference) // "Genesis 1:1"

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code
• chapter (number): Chapter number
• verse (number): Verse number

Passage Methods

getPassage(versionId, usfm, format?, include_headings?, include_notes?)

Fetch a passage with formatted content. This is the recommended method for retrieving verse text to preserve proper formatting of paragraphs and tables.

Code
 
// Single verse
const verse = await bibleClient.getPassage(111, 'JHN.3.16')
console.log(verse.content) // "<p>For God so loved the world...</p>"

// Verse range
const passage = await bibleClient.getPassage(111, 'GEN.1.1-5')

// Entire chapter
const chapter = await bibleClient.getPassage(111, 'GEN.1')

// With formatting options
const formatted = await bibleClient.getPassage(111, 'JHN.3.16', 'html', true, true)

Parameters:

• versionId (number): Bible version ID
• usfm (string): USFM reference format (e.g., "JHN.3.16", "GEN.1.1-5", "MAT.1")
• format (string, optional): "html" or "text" (default: "html")
• include_headings (boolean, optional): Include section headings in output
• include_notes (boolean, optional): Include footnotes/endnotes in output

Response:

Code
 
{
  id: "JHN.3.16",
  bible_id: 111,
  human_reference: "John 3:16",
  content: "<p><span class=\"verse-num\">16</span> For God so loved the world...</p>"
}

Index & VOTD Methods

getIndex(versionId)

Fetch the complete indexing structure for a Bible version.

Code
 
const index = await bibleClient.getIndex(111)
console.log(index.books[0].chapters.length)

Parameters:

• versionId (number): Bible version ID

Response:

Code
 
{
  id: 111,
  abbreviation: "NIV",
  books: [
    {
      id: "GEN",
      title: "Genesis",
      chapters: [
        { id: "1", verses: [{ id: "1" }, { id: "2" }, ...] },
        ...
      ]
    },
    ...
  ]
}

getAllVOTDs()

Fetch the Verse of the Day for the entire year.

Code
 
const allVOTDs = await bibleClient.getAllVOTDs()
console.log(allVOTDs.data[0].day) // 1 (January 1st)
console.log(allVOTDs.data[0].passage_id) // "JHN.3.16"

getVOTD(day)

Fetch the Verse of the Day for a specific day of the year.

Code
 
const votd = await bibleClient.getVOTD(1) // Day 1 (January 1st)
console.log(votd.passage_id) // "JHN.3.16"

Parameters:

• day (number): Day of the year (1-366)

LanguagesClient API

The LanguagesClient provides methods for accessing language information.

Code
 
import { LanguagesClient } from '@youversion/platform-core'

const languagesClient = new LanguagesClient(apiClient)

Language Methods

getLanguages(options)

Fetch available languages supported in the platform.

Code
 
// Get languages available in United States
const usLanguages = await languagesClient.getLanguages({
  country: 'US',
})

// Get with pagination
const page2 = await languagesClient.getLanguages({
  country: 'US',
  page_size: 10,
  page_token: 'next_page_token_from_previous_response',
})

Parameters:

• options (object):
  • country (string, required): ISO 3166-1 alpha-2 country code (e.g., "US", "BR", "MX")
  • page_size (number, optional): Results per page
  • page_token (string, optional): Pagination token from previous response

Response:

Code
 
{
  data: [
    {
      id: "en",
      language: "en",
      script: "Latn",
      display_names: { "en": "English" },
      countries: ["US"],
      text_direction: "ltr"
    }
  ]
}

getLanguage(languageId)

Fetch details about a specific language.

Code
 
const english = await languagesClient.getLanguage('en')
console.log(english.display_names?.en) // "English"

// With script specification
const serbianCyrillic = await languagesClient.getLanguage('sr-Cyrl')

Parameters:

• languageId (string): BCP 47 language code (e.g., "en", "es", "sr-Cyrl")

Troubleshooting: If you get "Language ID must match BCP 47 format" error, use proper language codes:

Code
 
await languagesClient.getLanguage('en')      // ✓ English
await languagesClient.getLanguage('es')      // ✓ Spanish
await languagesClient.getLanguage('sr-Cyrl') // ✓ Serbian Cyrillic
await languagesClient.getLanguage('zh-Hans') // ✓ Chinese Simplified

Referenced Types

These types are imported from @youversion/platform-core and represent the data structures used throughout the TypeScript SDK.

BibleVersion

Represents a Bible translation with metadata including language, copyright, and available books.

Types
 
type BibleVersion = {
  id: number;
  abbreviation: string;
  /** Long copyright text */
  copyright_long: string;
  /** Short copyright text */
  copyright_short: string;
  /** Bible information text */
  info?: string | null;
  publisher_url?: URL | null;
  language_tag: string;
  /** Localized abbreviation */
  local_abbreviation: string;
  /** Localized title */
  local_title: string;
  title: string;
  /** Array of books in this version */
  books: string[];
  /** YouVersion deep link URL */
  youversion_deep_link: URL;
};

BibleBook

Represents a book of the Bible with its chapters and canonical section.

Types
 
type BibleBook = {
  /** Book identifier (e.g., "MAT") */
  id: string;
  /** Book title (e.g., "Matthew") */
  title: string;
  /** Book abbreviation (e.g., "Matt") */
  abbreviation?: string;
  /** Canonical section "Old Testament", "New Testament", or "Deuterocanonical" */
  canon: 'ot' | 'nt' | 'dc';
  /** Array of chapter identifiers (e.g., ["MAT.1", "MAT.2"]) */
  chapters?: string[];
};

BibleChapter

Represents a chapter within a book with its verses.

Types
 
type BibleChapter = {
  /** Chapter identifier (e.g., "1") */
  id: string;
  /** Book identifier (e.g., "MAT") */
  book_id: string;
  /** Passage identifier (e.g., "MAT.1") */
  passage_id: string;
  /** Chapter title (e.g., "1") */
  title: string;
  /** Array of verse identifiers (e.g., ["1", "2", "3"]) */
  verses?: string[];
};

BibleVerse

Represents a single verse with its reference information.

Types
 
type BibleVerse = {
  /** Verse identifier (e.g., "1") */
  id: string;
  /** Book identifier (e.g., "MAT") */
  book_id: string;
  /** Chapter identifier (e.g., "1") */
  chapter_id: string;
  /** Passage identifier (e.g., "MAT.1.1") */
  passage_id: string;
  /** Human-readable reference (e.g., "Matthew 1:1") */
  reference: string;
};

BiblePassage

Represents formatted passage content for display.

Types
 
type BiblePassage = {
  /** Passage identifier (e.g., "MAT.1.1") */
  id: string;
  /** Passage content text (HTML or plain text) */
  content: string;
  /** Bible version identifier */
  bible_id: number;
  /** Human-readable reference (e.g., "Matthew 1:1") */
  human_reference: string;
};

VOTD (Verse of the Day)

Represents the Verse of the Day for a specific day of the year.

Types
 
type VOTD = {
  /** Day of the year (1-366), with 1 being January 1st */
  day: number;
  /** USFM passage identifier for this day's verse */
  passage_id: string;
};

Collection

Generic wrapper type for paginated API responses used across multiple endpoints.

Types
 
type Collection<T> = {
  /** Array of items in this page */
  data: T[];
  /** Token for fetching the next page, or null if this is the last page */
  next_page_token: string | null;
  /** Total number of items across all pages (optional) */
  total_size?: number;
};

Note: T is replaced with the specific item type in actual usage (e.g., Collection<BibleVersion>, Collection<BibleBook>, Collection<Language>).

Language

Represents a language supported by the YouVersion Platform with metadata.

Types
 
type Language = {
  /** BCP 47 language identifier (e.g., "en", "sr-Latn") */
  id: string;
  /** ISO 639 language code */
  language: string;
  /** ISO 15924 script code (e.g., "Latn") */
  script?: string | null;
  /** Script name (e.g., "Latin") */
  script_name?: string | null;
  /** Language aliases */
  aliases?: string[];
  /** Display names for different locales (e.g., { en: "English", fr: "Anglais" }) */
  display_names?: Record<string, string>;
  /** Available scripts for this language (e.g., ["Cyrl", "Latn"]) */
  scripts?: string[];
  /** Language variants (e.g., ["1996", "fonipa"]) */
  variants?: string[];
  /** ISO 3166-1 alpha-2 country codes where this language is spoken */
  countries?: string[];
  /** Text direction: "ltr" (left-to-right) or "rtl" (right-to-left) */
  text_direction?: 'ltr' | 'rtl';
  /** Writing population count */
  writing_population?: number;
  /** Speaking population count */
  speaking_population?: number;
  /** Default Bible version ID for this language */
  default_bible_version_id?: number | null;
};

Copyright & Attribution

Always fetch the version's copyright information and display it alongside Bible text:

Code
 
const passage = await bibleClient.getPassage(111, 'JHN.3.16')
const version = await bibleClient.getVersion(111)

// Display both content and copyright
console.log(passage.content)
console.log(version.copyright_short) // Required attribution

Server-side rendering example:

Code
 
async function renderBiblePage(reference: string, versionId: number) {
  const passage = await bibleClient.getPassage(versionId, reference)
  const version = await bibleClient.getVersion(versionId)
  
  return `
    <article>
      <h1>${passage.human_reference}</h1>
      <div class="passage">${passage.content}</div>
      <footer>
        <p class="copyright">${version.copyright_short}</p>
      </footer>
    </article>
  `
}

Copyright fields in BibleVersion:

• copyright_short - Brief attribution (display after verses)
• copyright_long - Full copyright notice (use in settings/about pages)
• publisher_url - Optional link to publisher