Guides

Search

Copy page

Use SearchClient from @youversion/platform-core to search a Bible version or find related topics. 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 when you need to page through verse 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:

Code
npm install @youversion/platform-core

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

Search uses your App Key. You do not need to sign in a user.

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. Treat tokens as opaque values; do not parse or construct them.

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 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 a nonempty array in the fourth argument, such as { fields: ["verses", "topics"] }. See Language ranges for supported input and fallback behavior.

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

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.