YouVersion PlatformYouVersion Platform
PlatformContent LibraryDev Docs
CommunityPartnersSupport

YouVersion Platform

Build applications and integrate with the world's most popular Bible platform.

Platform Products

  • Platform Portal
  • Developer Documentation
  • App Management

Resources

  • Support
  • Press inquiries

Legal

  • Privacy Policy
  • Terms of Use

© 2026 YouVersion. All rights reserved.

  • Overview
  • API Reference
  • SDKs
  • Changelog
<  Back to Platform
SDK Introduction
Swift SDK
Kotlin SDK
JavaScript SDK
    Quick StartJavaScript SDK API referenceTypeScript Types
    Guides
      Copyright & AttributionSearchVerse images
React SDK
React Native (Expo) SDK
Guides

Search

Use SearchClient from @youversion/platform-core to search Bible verses, related topics, and verse images. The same client works in JavaScript and TypeScript applications without React.

For a general search box, use unified search to retrieve multiple kinds of results, such as verse references and related topics, in one request. You can also search for a specific kind of content with searchVerses or searchTopics. Use searchVerses to page through verse results or searchImages to page through image results.

Search returns passage identifiers and metadata, not passage text. To display a passage, fetch its content using the Bible APIs.

Requirements

Get an App Key from YouVersion Platform.

Install the core package:

TerminalCode
npm install @youversion/platform-core

For other package managers, see the core SDK installation instructions.

Search uses your App Key. The image-search example requires @youversion/platform-core 2.17.0 or later.

Search verses

Create an ApiClient with your App Key and pass it to SearchClient. Replace YOUR_APP_KEY with your App Key before running the example.

Run this code in a JavaScript or TypeScript module that supports top-level await:

Code
import { ApiClient, SearchClient } from "@youversion/platform-core"; const apiClient = new ApiClient({ appKey: "YOUR_APP_KEY" }); const search = new SearchClient(apiClient); const results = await search.searchVerses("love", 3034, { pageSize: 25, }); for (const verse of results.verses) { console.log(verse.id); }

On success, the example logs each returned passage identifier, such as JHN.3.16. If you need its book, chapter, or verse numbers, use parseUsfmReference.

The remaining examples reuse search and apiClient from this example.

Load another page

To load results when the user chooses Load more, retain the response's nextPageToken and pass it as pageToken in the next request. Keep the query, Bible version, intent, and page size the same.

Code
const query = "love"; const versionId = 3034; const options = { pageSize: 25 }; const firstPage = await search.searchVerses(query, versionId, options); const verses = [...firstPage.verses]; let nextPageToken = firstPage.nextPageToken; async function loadMore() { if (!nextPageToken) return; const nextPage = await search.searchVerses(query, versionId, { ...options, pageToken: nextPageToken, }); verses.push(...nextPage.verses); nextPageToken = nextPage.nextPageToken; }

Connect loadMore to your interface's Load more action. Disable that action while a request is in progress to avoid requesting the same page twice. Each call appends one page to verses.

A missing or null nextPageToken means there are no more pages.

Display a passage

Use BibleClient to fetch passage text. This example uses results from the first verse-search example:

Code
import { BibleClient } from "@youversion/platform-core"; const bible = new BibleClient(apiClient); const firstResult = results.verses[0]; if (firstResult) { const passage = await bible.getPassage(3034, firstResult.id, "text"); console.log(passage.content); }

This example logs plain text. If you display Bible content in your application, include the required copyright and attribution. If you use React, you can display the passage with attribution through BibleCard.

Search verses and topics together

Call searchUnified to retrieve top results across content kinds, such as verse references and related topics, in one request.

You must supply both a Bible version ID and language preferences. The Bible version selects the text and language for verse results; the preferences select the language for topic and image results:

Code
const results = await search.searchUnified("faith", 3034, ["en"]); for (const verse of results.verses) { console.log(verse.id); } for (const topic of results.topics) { console.log(topic.text, topic.subtopics); }

The response is one snapshot of top results, not the full verse result set. It has no pagination. To load more verses, start a separate searchVerses request with the same query and Bible version, then use its pagination tokens.

Omit fields to request all result kinds. To select kinds, pass an array in the fourth argument, such as { fields: ["verses", "topics"] }. See Language ranges for supported input and fallback behavior.

Verse results contain passage IDs, not text. Use the passage example to display them. The response also includes query-correction metadata; see the searchUnified reference.

Search images

Use searchImages to find art that matches freeform text, one page at a time. The Bible version selects the search language. To list the art for a passage that you already know, use getImages instead.

This example loads the first page and logs each related image's passage identifier:

Code
import { ApiClient, ImagesClient, SearchClient } from "@youversion/platform-core"; const apiClient = new ApiClient({ appKey: "YOUR_APP_KEY" }); const search = new SearchClient(apiClient); const images = new ImagesClient(apiClient); const imageQuery = "love"; const imageVersionId = 3034; const imagePageSize = 25; const imagePage = await search.searchImages(imageQuery, imageVersionId, { pageSize: imagePageSize, }); for (const relatedImage of imagePage.images) { console.log(relatedImage.passageId); }

Each related image has an id and a passageId. To get an image's URL and attribution, pass its id to images.getImage. A search might find no related images. See Verse Images for rendition sizes, optional credits, and caching.

Load another image page

Pass the response's nextPageToken as pageToken. Keep the query, Bible version, and page size unchanged:

Code
if (imagePage.nextPageToken !== null) { const nextImagePage = await search.searchImages(imageQuery, imageVersionId, { pageSize: imagePageSize, pageToken: imagePage.nextPageToken, }); for (const relatedImage of nextImagePage.images) { console.log(relatedImage.passageId); } }

An empty images array does not necessarily end pagination. Continue until nextPageToken is null. For a Load more interface, disable the action while a request is in progress to avoid loading the same page twice. See the searchImages reference for limits and response fields.

Search topics

Use searchTopics to find related topics without choosing a Bible version. Pass a language range, such as "en" for English or "*" for all languages, or an ordered array of language preferences. See Language ranges for language selection.

Code
const results = await search.searchTopics("faith", ["en-US", "en"]); for (const topic of results.topics) { console.log(topic.text); for (const subtopic of topic.subtopics) { console.log(subtopic); } }

If a user selects a topic or subtopic, use its label as the query for a verse search with topical intent:

Code
const selectedTopic = results.topics[0]; if (selectedTopic) { const verses = await search.searchVerses(selectedTopic.text, 3034, { userIntent: "topical", }); console.log(verses.verses); }

Suggest queries

Use getSuggestedQueries for nonempty partial input:

Code
const suggestions = await search.getSuggestedQueries("lo", "en"); for (const suggestion of suggestions.queries) { console.log(suggestion.text); }

The core SDK does not wait for typing to pause or discard outdated responses. Manage these behaviors in your interface:

  • Wait for typing to pause before requesting suggestions. This delay is called a debounce.
  • If the user changes the input, ignore responses for the previous input.

If you use React, build a custom interface with useBibleSearch to manage these behaviors.

Load trending queries

If the search field is empty, use getTrendingQueries to request popular queries:

Code
const trending = await search.getTrendingQueries("en"); for (const query of trending.queries) { console.log(query.text); }

Request verse or topic results after the user selects a query. Do not preload results for each suggestion or trending query.

Set search intent

Leave userIntent unset unless you are fairly certain what kind of match the user wants. If your interface establishes the intent, pass one of these values to searchVerses or searchUnified:

  • "unknown": Let the service determine the intent.
  • "reference": Look up a scripture reference, such as "John 3:16".
  • "text": Find words or phrases in Bible text.
  • "topical": Find verses related to a topic.

Offer query corrections

Use didYouMean from a verse, topic, or unified response to offer alternative spellings as new searches:

Code
const results = await search.searchVerses("watr", 3034); for (const alternative of results.didYouMean) { console.log(alternative); }

For parameter limits and response fields, see the SearchClient reference.

Last modified on November 17, 2026
Copyright & AttributionVerse images
On this page
  • Requirements
  • Search verses
    • Load another page
    • Display a passage
  • Search verses and topics together
  • Search images
    • Load another image page
  • Search topics
  • Suggest queries
  • Load trending queries
  • Set search intent
  • Offer query corrections
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript