Core

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

Installation

Install the package with your preferred package manager:

Configuration

Create an API client with your App Key:

Code
import { ApiClient, BibleClient, LanguagesClient } from "@youversion/platform-core";

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

const bibleClient = new BibleClient(apiClient);
const languagesClient = new LanguagesClient(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: 3034,
      abbreviation: "BSB",
      localized_abbreviation: "BSB",
      title: "Berean Standard Bible",
      localized_title: "Berean Standard Bible",
      language_tag: "en",
      copyright: "...",
      books: ["GEN", "EXO", ...],
      publisher_url: "https://...",
      youversion_deep_link: "https://www.bible.com/versions/3034"
    }
  ]
}

getVersion(id)

Fetch a specific Bible version by ID.

Code
const bibleVersion = await bibleClient.getVersion(3034);
console.log(bibleVersion.title); // "Berean Standard Bible"

Parameters:

• id (number): Bible version ID

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(3034);

Parameters:

• versionId (number): Bible version ID

Response:

Code
{
  data: [
    {
      id: "GEN",
      title: "Genesis",
      full_title: "Genesis",
      abbreviation: "Gen.",
      canon: "old_testament",
      intro: { id: "INTRO", passage_id: "GEN.INTRO", title: "Intro" },
      chapters: [
        { id: "1", passage_id: "GEN.1", title: "1", verses: [ { id: "1", passage_id: "GEN.1.1", title: "1" }, ... ] },
        { id: "2", passage_id: "GEN.2", title: "2", verses: [...] },
        ...
      ]
    }
  ]
}

getBook(versionId, book)

Fetch a specific book by its USFM identifier.

Code
const genesis = await bibleClient.getBook(3034, "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(3034, "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(3034, "GEN", 1);
console.log(genesis1.title); // "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(3034, "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: "1", passage_id: "GEN.1.1", title: "1" },
    { id: "2", passage_id: "GEN.1.2", title: "2" },
  ];
}

getVerse(versionId, book, chapter, verse)

Fetch a specific verse.

Code
const verse = await bibleClient.getVerse(3034, "GEN", 1, 1);
console.log(verse.passage_id); // "GEN.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 (request HTML)
const verse = await bibleClient.getPassage(3034, "JHN.3.16", "html");
console.log(verse.content); // "<div><div class=\"p\">..."

// Verse range (plain text by default)
const passage = await bibleClient.getPassage(3034, "GEN.1.1-5");

// Entire chapter
const chapter = await bibleClient.getPassage(3034, "GEN.1");

// With formatting options
const formatted = await bibleClient.getPassage(
  3034,
  "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: "text")
• include_headings (boolean, optional): Include section headings in output
• include_notes (boolean, optional): Include footnotes/endnotes in output

Choosing a Format

• "text" (default) — Plain text with no markup. Easy to display in any framework or environment. Recommended for most non-React apps that don't need formatted output.
• "html" — Returns HTML with YouVersion-specific CSS classes for verse numbers, paragraphs, headings, poetry, tables, and more. If you're using React, use the BibleTextView or BibleReader components which handle styling and footnotes automatically.

Response:

format: text
{
  "id": "JHN.3.16",
  "content": "For God so loved the world that He gave His one and only Son, that everyone who believes in Him shall not perish but have eternal life.",
  "reference": "John 3:16"
}

format: html
{
  "id": "JHN.3.16",
  "content": "<div class=\"p\"><span class=\"yv-v\" v=\"16\"></span><span class=\"yv-vlbl\">16</span>For God so loved the world...</div>",
  "reference": "John 3:16"
}

Index & VOTD Methods

getIndex(versionId)

Fetch the complete indexing structure for a Bible version.

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

Parameters:

• versionId (number): Bible version ID

Response:

Code
50;

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",
      script_name: "Latin",
      display_names: { en: "English" },
      countries: ["US"],
      text_direction: "ltr",
      default_bible_id: 3034,
    },
  ];
}

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")

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