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
    Quick StartComponents
    Guides
      SearchVerse imagesReader Navigation and ToolbarsCopyright & Attribution
Kotlin SDK
JavaScript SDK
React SDK
React Native (Expo) SDK
Guides

Search

Search APIs

Overview

Paginated image search requires SDK 5.7.0 or later.

Use YouVersionAPI.Search to find Bible references, related topics, and verse images. 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 let images = results.images

Search returns references, related images, 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. bibleID identifies the Bible version. Invalid inputs checked by the SDK throw YouVersionAPIRequestError with code .invalidParameter.

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

MethodReturnsUse case
unified(matching:bibleID:languageRanges:)YouVersionSearchResultsTop verse references, related topics, and related images in one request
verses(query:bibleID:)YouVersionVerseSearchResultsVerse references with pagination
images(query:bibleID:)YouVersionImageSearchResultsRelated images, with pagination
topics(matching:languageRanges:)YouVersionTopicSearchResultsRelated 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, topics, and images. Omit fields to include all three kinds, or pass any combination of "verses", "topics", and "images". Query metadata is always included.

Unified search requires both bibleID and languageRanges. The Bible version selects the text and language for verse results; the language preferences select the language for topic and image results.

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.

Each item in images is a YouVersionSearchImage with an id and a passageID. Pass the id to YouVersionAPI.Images.image(id:) to load the image URL and attribution. A search might find no related images. See Verse Images.

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.

Image Search

Call images(query:bibleID:) to find art that matches freeform text in one Bible version. To list the art for a passage that you already know, use YouVersionAPI.Images.images(passageID:) instead.

The method returns YouVersionImageSearchResults with images and an optional nextPageToken. This example loads the first page, then loads the next page when there is one:

Code
let query = "love" let bibleID = 3034 let firstPage = try await YouVersionAPI.Search.images( query: query, bibleID: bibleID, pageSize: 25 ) var images = firstPage.images var nextPageToken = firstPage.nextPageToken if let pageToken = nextPageToken { let nextPage = try await YouVersionAPI.Search.images( query: query, bibleID: bibleID, pageSize: 25, pageToken: pageToken ) images.append(contentsOf: nextPage.images) nextPageToken = nextPage.nextPageToken }

Repeat the second step when the user requests more images. Keep the query, Bible version, and page size unchanged between pages. pageSize accepts 1 through 99. Stop only when nextPageToken is nil. An empty page can include a continuation token. A search might find no related images.

Each item in images is a YouVersionSearchImage with an id and a passageID. To load an image's URL and attribution, pass its id to YouVersionAPI.Images.image(id:). See Verse Images to display it.

bibleID determines the language searched. Request, network, and decoding failures throw.

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

Pass languageRanges as an array, such as ["en-US", "en"], for unified search, topic search, suggestions, and trending queries. Use ["*"] to match all languages. See Language ranges for language selection.

Search Intent

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

ValueUse case
.unknownLet the service determine the intent
.referenceLook up a scripture reference, such as "John 3:16"
.textFind words or phrases in Bible text
.topicalFind 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:

PropertyMeaning
didYouMeanAn array of suggested alternative spellings
searchInsteadForAn 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)?") }
Last modified on November 17, 2026
ComponentsVerse images
On this page
  • Search APIs
    • Overview
    • Unified Search
    • Verse Search
    • Image Search
    • Topics Search
    • Suggested Queries
    • Trending Queries
  • Parameters
    • Language Ranges
    • Search Intent
    • Query Corrections
Swift
Swift
Swift
Swift
Swift
Swift
Swift
Swift
Swift