Guides

Search

Copy page

BibleReader includes search with nothing to configure — see Search in the reader. This guide is for apps building their own search UI on the search endpoints directly.

Requirements

• platform-core 2.1.0 or later for YouVersionApi.search, and platform-reader 2.2.0 or later for search in BibleReader. Earlier versions have no search property, so the samples below will not compile against them.
• A configured app key. Set up the SDK as shown in the Quick Start. The user does not have to be signed in.

To raise the versions in an existing project:

build.gradle.kts
dependencies {
    implementation("com.youversion.platform:platform-core:2.+")
    implementation("com.youversion.platform:platform-ui:2.+")
    implementation("com.youversion.platform:platform-reader:2.+")
}

Keep every module on the same version. Upgrading from 1.x crosses the 2.0.0 breaking changes; see the changelog before upgrading.

Choose a search method

All methods are suspend functions on YouVersionApi.search.

Method	Returns	Use case
unified(query, bibleId, languageRanges)	SearchResults	Top verse references and related topics in one request
verses(query, bibleId)	VerseSearchResults	Verse references with pagination
topics(query, languageRanges)	TopicSearchResults	Related topics and subtopics
suggestedQueries(query, languageRanges)	List<SearchQuery>	Suggestions while the user types
trendingQueries(languageRanges)	List<SearchQuery>	Queries many readers are running right now

Search for references and topics

Call search from a coroutine, such as one launched in viewModelScope:

SearchViewModel.kt
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.youversion.platform.core.api.YouVersionApi
import com.youversion.platform.core.api.YouVersionNetworkException
import com.youversion.platform.core.search.models.SearchResults
import java.io.IOException
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.launch

class SearchViewModel : ViewModel() {
    private val _results = MutableStateFlow<SearchResults?>(null)
    val results: StateFlow<SearchResults?> = _results

    private val _error = MutableStateFlow<String?>(null)
    val error: StateFlow<String?> = _error

    private var searchJob: Job? = null

    fun search(query: String) {
        searchJob?.cancel()
        searchJob = viewModelScope.launch {
            _error.value = null
            try {
                _results.value = YouVersionApi.search.unified(
                    query = query,
                    bibleId = 3034,
                    languageRanges = listOf("en"),
                )
            } catch (e: IllegalArgumentException) {
                _error.value = "Check your search and try again."
            } catch (e: YouVersionNetworkException) {
                _error.value = "Search couldn't complete."
            } catch (e: IOException) {
                _error.value = "No connection. Try again when you're online."
            }
        }
    }
}

An exception that escapes a coroutine in viewModelScope crashes the app, so catch search failures inside the coroutine. Cancel the previous search before starting a new one, so a slower, older response can't overwrite the newer query's results or error. Error handling describes each failure type.

Search returns references and metadata, without passage text. Each verse result in references is a single-verse BibleReference in the requested Bible version. Pass it to a Bible component, such as BibleCard, to fetch and display the passage with attribution. bibleId is the same Bible version id the rest of the SDK calls versionId.

Unified search returns one unpaginated set of top results grouped into references and topics. To limit the kinds of results, pass fields with "verses", "topics", or both; leave it empty to include both. Ask only for the kinds you display:

Code
YouVersionApi.search.unified(
    query = "faith",
    bibleId = 3034,
    languageRanges = listOf("en"),
    fields = listOf("topics"),
)

Unified search has no pageSize, pageToken, or nextPageToken. Use verses to load more verse results.

Page through verse results

verses returns references in rank order, one page at a time. To load another page, pass the previous page's nextPageToken as pageToken, keeping the query, Bible version, intent, and page size the same:

Code
import com.youversion.platform.core.api.YouVersionApi
import com.youversion.platform.core.search.models.SearchUserIntent

suspend fun loadPage(pageToken: String? = null) =
    YouVersionApi.search.verses(
        query = "love",
        bibleId = 3034,
        userIntent = SearchUserIntent.text,
        pageSize = 25,
        pageToken = pageToken,
    )

val firstPage = loadPage()
val secondPage = firstPage.nextPageToken?.let { token -> loadPage(token) }

Leave pageSize null to use the platform's default. A null nextPageToken means there are no more pages.

Find related topics

topics returns related topics without requiring a Bible version. Each SearchTopic contains a text label and a list of subtopics labels.

Code
import com.youversion.platform.core.api.YouVersionApi

val results = YouVersionApi.search.topics(
    query = "faith",
    languageRanges = listOf("en"),
)

results.topics.forEach { topic ->
    println(topic.text)
    topic.subtopics.forEach { subtopic -> println(subtopic) }
}

Use a topic or subtopic label as the query for a new verse search with userIntent = SearchUserIntent.topical. Topic search is unpaginated — there is no page token and no total count.

Suggested and trending queries

As the user types, request suggestions for the partial query. When the search field is empty, you can show trending queries instead:

Code
import com.youversion.platform.core.api.YouVersionApi

val suggestions = YouVersionApi.search.suggestedQueries(
    query = "lo",
    languageRanges = listOf("en"),
)

val trending = YouVersionApi.search.trendingQueries(languageRanges = listOf("en"))

Debounce input changes and discard responses for outdated input before updating your suggestions.

Both methods return List<SearchQuery>. Each query has text and an optional source string, and the list is empty when the platform has nothing to offer. Only after the user selects a suggested or trending query should you run it through unified or verses to retrieve results.

Parameters

The SDK checks these constraints before sending a request and throws IllegalArgumentException if an argument breaks one.

Parameter	Constraint
query	1–100 grapheme clusters (characters as the user sees them, so an emoji counts as one) for unified, verses, and topics; non-empty for suggestedQueries
bibleId	Greater than zero
pageSize	1 through 99, or null for the platform's default
languageRanges	At least one entry, each a well-formed language tag

Language ranges

languageRanges is required for unified search, topic search, suggestions, and trending queries. Supply an ordered list of BCP 47 language tags, such as listOf("en-US", "en"). The platform answers in the first language it supports. For unified search, bibleId selects the Bible version for verse results.

Use concrete language tags. The SDK accepts a bare "*", but the search service rejects it, so the request fails with CANNOT_DOWNLOAD.

User intent

Unified and verse search accept a SearchUserIntent. The default is SearchUserIntent.unknown.

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

The returned userIntent is nullable and describes the intent the platform inferred. The set of intents is open: the platform may return one this version of the SDK does not name, and it arrives intact in rawValue rather than failing the search. A when over it therefore needs an else branch:

Code
val heading = when (results.userIntent) {
    SearchUserIntent.reference -> "Passages"
    SearchUserIntent.topical -> "Topics"
    else -> "Results"
}

Query corrections

Unified, verse, and topic results include correction metadata:

Property	Meaning
didYouMean	A list of alternative spellings, offered alongside results for the query as written
searchInsteadFor	The user's original wording, present only when the platform corrected the query and returned results for the correction

For example, a search for "watr" might return results for a correction along with the original wording:

Code
import com.youversion.platform.core.api.YouVersionApi

val results = YouVersionApi.search.unified(
    query = "watr",
    bibleId = 3034,
    languageRanges = listOf("en"),
)

results.searchInsteadFor?.let { original ->
    println("Search instead for $original")
}

results.didYouMean.forEach { alternative ->
    println("Did you mean $alternative?")
}

Error handling

Search reports failure in three ways:

Failure	Thrown	Meaning
Invalid argument	IllegalArgumentException	An argument broke a parameter constraint; no request was made
Error response	YouVersionNetworkException	NOT_PERMITTED when the app key is invalid or lacks access, CANNOT_DOWNLOAD for any other error response, INVALID_RESPONSE when the response cannot be read
No response	java.io.IOException	The device is offline, DNS lookup failed, or the connection timed out. The SDK does not wrap these in YouVersionNetworkException

CANNOT_DOWNLOAD does not say which status the server returned, so it covers both permanent failures, such as a bibleId the app cannot access, and temporary ones, such as a rate limit. Report that search couldn't complete rather than promising that a retry or a different Bible version will fix it. To rule out an inaccessible version, check the app's available Bibles before searching.

A response with no content (HTTP 204) is handled differently by endpoint. trendingQueries and suggestedQueries return an empty list, while verses, topics, and unified throw YouVersionNetworkException with reason INVALID_RESPONSE rather than reporting no matches.

Code
import com.youversion.platform.core.api.YouVersionApi
import com.youversion.platform.core.api.YouVersionNetworkException
import java.io.IOException

try {
    val results = YouVersionApi.search.verses(query = userQuery, bibleId = 3034)
    showResults(results.references)
} catch (e: IllegalArgumentException) {
    // Validate input against the parameter constraints before searching
} catch (e: YouVersionNetworkException) {
    when (e.reason) {
        YouVersionNetworkException.Reason.NOT_PERMITTED -> showConfigurationError()
        else -> showSearchUnavailable()
    }
} catch (e: IOException) {
    // No response arrived, so a retry may succeed
    showConnectionError()
}

To call the same endpoints outside the SDK, see the search API guide.