Guides

Search

Copy page

Search APIs

Overview

Use YouVersionAPI.Search to find Bible references and related topics. Configure the SDK as shown in the Quick Start, then call the search methods from an asynchronous context with try await.

Code
import YouVersionPlatform

let results = try await YouVersionAPI.Search.unified(
    matching: "love",
    bibleID: 3034,
    languageRanges: ["en"]
)

let references = results.references
let topics = results.topics

Search returns references and metadata, without passage text. The SDK converts verse results into BibleReference values using the requested bibleID. Pass a reference to a Bible component, such as BibleCardView(reference:), to fetch and display the passage with attribution.

Validation and errors

All search methods are async throws. Unified, verse, and topic queries must contain 1–100 characters. Suggested queries must be nonempty. Bible IDs must be positive integers representable as Int32, and supplied language ranges must be valid and nonempty. Invalid inputs checked by the SDK throw YouVersionAPIRequestError with code .invalidParameter.

Handle request failures with do/catch in your calling code. Requests can also throw network, API, or decoding errors. Every method accepts an optional accessToken override and a session parameter; by default, they use YouVersionPlatformConfiguration.accessToken and URLSession.shared.

Search methods

Method	Returns	Use case
unified(matching:bibleID:languageRanges:)	YouVersionSearchResults	Top verse references and related topics in one request
verses(query:bibleID:)	YouVersionVerseSearchResults	Verse references with pagination
topics(matching:languageRanges:)	YouVersionTopicSearchResults	Related topics and subtopics
suggestedQueries(matching:languageRanges:)	[YouVersionSearchQuery]	Suggestions while the user types
trendingQueries(languageRanges:)	[YouVersionSearchQuery]	Recently popular searches

Unified Search

Unified search returns one unpaginated set of top results grouped into references and topics. Omit fields to include both kinds, or pass "verses", "topics", or both. Query metadata is always included.

Code
let results = try await YouVersionAPI.Search.unified(
    matching: "faith",
    bibleID: 3034,
    languageRanges: ["en"],
    userIntent: .topical,
    fields: ["verses", "topics"]
)

for topic in results.topics {
    print(topic.text)
}

Use verses when you need to load additional verse results. Unified search has no pageSize, pageToken, or nextPageToken.

Verse Search

Code
let results = try await YouVersionAPI.Search.verses(
    query: "love",
    bibleID: 3034,
    userIntent: .text,
    pageSize: 25
)

let references = results.references

pageSize accepts values from 1 through 99. When omitted, the API defaults to 25.

To load another page, pass nextPageToken as pageToken, keeping the query, Bible version, intent, and page size the same:

Code
let query = "love"
let bibleID = 3034
let firstPage = try await YouVersionAPI.Search.verses(
    query: query,
    bibleID: bibleID,
    userIntent: .text,
    pageSize: 25
)

var references = firstPage.references
var nextPageToken = firstPage.nextPageToken

if let pageToken = nextPageToken {
    let nextPage = try await YouVersionAPI.Search.verses(
        query: query,
        bibleID: bibleID,
        userIntent: .text,
        pageSize: 25,
        pageToken: pageToken
    )

    references.append(contentsOf: nextPage.references)
    nextPageToken = nextPage.nextPageToken
}

Repeat this step when the user requests more results. A nil nextPageToken means there are no more pages.

Topics Search

Topic search returns related topics without requiring a Bible version. Each YouVersionSearchTopic contains a text label and an array of subtopics labels.

Code
let results = try await YouVersionAPI.Search.topics(
    matching: "faith",
    languageRanges: ["en"]
)

for topic in results.topics {
    print(topic.text)
    for subtopic in topic.subtopics {
        print(subtopic)
    }
}

Use a topic or subtopic label as the query for a new verse search with userIntent: .topical. Topic search is unpaginated.

Suggested Queries

Request suggestions for a nonempty partial query as the user types:

Code
let suggestions = try await YouVersionAPI.Search.suggestedQueries(
    matching: "lo",
    languageRanges: ["en"]
)

for suggestion in suggestions {
    print(suggestion.text)
}

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

Trending Queries

When the search field is empty, you can show recently popular queries:

Code
let trending = try await YouVersionAPI.Search.trendingQueries(
    languageRanges: ["en"]
)

Both methods return [YouVersionSearchQuery]. Each query has text and an optional source string, such as "community" or "trending". The SDK returns an empty array when the API responds with no content. Only after the user selects a suggested or trending query should you run it through unified or verses to retrieve results. Do not preload results for these queries.

Parameters

Language Ranges

languageRanges is required for unified search, topic search, suggestions, and trending queries. Supply a nonempty, ordered array of canonical BCP 47 language tags, such as ["en-US", "en"], or use ["*"] to match all languages. The service uses the first supported language range. For unified search, bibleID selects the Bible version for verse results.

Search Intent

Unified and verse search accept YouVersionSearchUserIntent. The default is .unknown.

Value	Use case
.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

The returned userIntent is optional and describes the intent resolved by the service. Read its rawValue when you need the string representation.

Query Corrections

Unified, verse, and topic results include correction metadata:

Property	Meaning
didYouMean	An array of suggested alternative spellings
searchInsteadFor	An optional corrected query that the returned results actually match

Code
let results = try await YouVersionAPI.Search.unified(
    matching: "watr",
    bibleID: 3034,
    languageRanges: ["en"]
)

if let correctedQuery = results.searchInsteadFor {
    print("Showing results for \(correctedQuery)")
}

for alternative in results.didYouMean {
    print("Did you mean \(alternative)?")
}