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

Verse images

Use the Images APIs to show verse art for the Verse of the Day, a search query, or a passage. This guide covers the Swift SDK. For direct HTTP requests and the rules that apply to every platform, see Verse Images. For other SDKs, see the image guides for JavaScript, React, React Native Expo, and Kotlin.

Images APIs

Overview

This guide uses SDK 5.7.0 or later.

Use YouVersionAPI.Images to find verse art for a passage and to load an image that search returns. Configure the SDK with your app key as shown in the Quick Start.

Code
import YouVersionPlatform let page = try await YouVersionAPI.Images.images( passageID: "JHN.3.16", languageRanges: ["en"] ) for image in page.images { print(image.url, image.attribution) }

Each YouVersionImage has a url that you load with AsyncImage or your own image loader, and an optional attribution credit line that you can show with the image.

Validation and errors

All image methods are async throws. pageSize must be from 1 through 99. Invalid inputs that the SDK checks throw YouVersionAPIRequestError with code .invalidParameter. Requests can also throw network, API, or decoding errors.

Images methods

MethodReturnsUse case
imagesYouVersionImageCollectionList images for a passage or language. passageID, languageRanges, pageSize, and pageToken are optional.
image(id:)YouVersionImageThe full record for an image id from search results or the Verse of the Day

List images for a passage

images(passageID:) lists the art for a passage that you already know. To find art that matches freeform text, such as "love", use Image Search instead.

Code
let page = try await YouVersionAPI.Images.images( passageID: "1CO.13.4-7", languageRanges: ["en"], pageSize: 10 ) var images = page.images if let pageToken = page.nextPageToken { let nextPage = try await YouVersionAPI.Images.images( passageID: "1CO.13.4-7", languageRanges: ["en"], pageSize: 10, pageToken: pageToken ) images.append(contentsOf: nextPage.images) }

passageID is one verse, such as JHN.3.16, or a verse range, such as 1CO.13.4-7. A verse range returns images for any verse in the range. Chapters, such as JHN.3, are not supported. To show art for a whole chapter, pass a verse range that covers the chapter. Omit passageID to browse art across all passages.

pageSize accepts values from 1 through 99. When omitted, the page size is 25. To load another page, pass nextPageToken as pageToken, with the same passageID and languageRanges. You can change pageSize between pages. A nil nextPageToken means there are no more pages. totalSize is the number of matching images across all pages. It is set only when you pass passageID, and it is nil otherwise.

Display an image

Add a size to the image URL, reserve space with aspectRatio, and, if you want a credit line, show attribution with the image:

Code
import SwiftUI import YouVersionPlatform struct VerseImageView: View { let image: YouVersionImage private var cardURL: URL { image.url.appending( queryItems: [URLQueryItem(name: "size", value: "card")] ) } var body: some View { VStack(alignment: .leading, spacing: 8) { AsyncImage(url: cardURL) { phase in if let artwork = phase.image { artwork.resizable().scaledToFit() } else { Color.secondary.opacity(0.2) } } .aspectRatio(image.aspectRatio, contentMode: .fit) .clipShape(.rect(cornerRadius: 12)) Text(image.attribution) .font(.caption) .foregroundStyle(.secondary) } } }

YouVersionImage has passageID and languageTag, but not verse text, an accessibility description, or a Bible version id. When the art conveys content that is not already on screen, pair it with a passage label or nearby text from a Bible component. When equivalent verse text is already accessible, you can hide redundant art from VoiceOver.

Set the URL's size query parameter to thumb, card, or full, preserving existing parameters. See Picking a size for width presets and image sizes.

Verse of the Day art

Requesting the day's selected image requires SDK 5.7.0 or later.

Request the day's passage and selected image with verseOfTheDay(dayOfYear:languageRanges:). Pass language ranges in order of preference. When the day has art, pass its imageID to image(id:):

Code
func votdImage( dayOfYear: Int, languageRanges: [String] ) async throws -> YouVersionImage? { let votd = try await YouVersionAPI.VOTD.verseOfTheDay( dayOfYear: dayOfYear, languageRanges: languageRanges ) guard let imageID = votd.imageID else { // No image is available for this day. return nil } return try await YouVersionAPI.Images.image(id: imageID) }

Pass the returned image to VerseImageView from Display an Image. imageID is nil when no art matches the requested languages. If you do not provide language ranges, you get no image data.

To fetch the full year's calendar, call YouVersionAPI.VOTD.versesOfTheDay(languageRanges:). It returns an array of YouVersionVerseOfTheDay records. See Images in Verse of the Day for language selection.

To find other art for the passage, use images(passageID: votd.passageId). Those images can differ from the day's selected image.

Images in unified search

Unified search finds verses, topics, and related images for a text query in one request. Use it for a combined search screen. Use images(passageID:) when you already know the passage. To load a related image from unified search, pass its id to image(id:). The Search guide shows the request.

Parameters

Language ranges

For YouVersionAPI.Images.images, languageRanges selects the language of the text on the art. Each range is a language tag, such as en or es. Unified search has different rules. See Language Ranges in the search guide. For how the Images API resolves ranges, see Language selection.

Swift callers often need these details:

  • Use base language tags, such as es. A regional tag such as es-MX returns no art, and the ranges after it are not tried, so ["es-MX", "es"] returns no art.
  • Chinese art uses region tags. Use zh-CN, zh-TW, or zh-HK, not zh.
  • Only the first language that the service recognizes is used. When that language has no art for the passage, the next range is not tried.
  • Pass ["*"], or omit languageRanges, to include every language.

This helper makes a range from the user's locale:

Code
func artLanguageRange(for locale: Locale = .current) -> String { guard let language = locale.language.languageCode?.identifier else { return "en" } guard language == "zh" || language == "yue" else { return language } let region = locale.region?.identifier let isHongKong = region == "HK" || region == "MO" let script = locale.language.script let isTraditional = script == .hanTraditional || ( script == nil && (language == "yue" || isHongKong || region == "TW") ) guard isTraditional else { return "zh-CN" } return isHongKong ? "zh-HK" : "zh-TW" }

Image fields

PropertyTypeDescription
idStringThe image id.
urlURLThe URL of the image file.
passageIDStringThe verse or verse range that the image shows, such as JHN.3.16.
attributionStringThe credit line for the image. Showing it is optional.
languageTagStringThe language of the text on the art, such as en.
width, heightIntThe original size in pixels.
aspectRatioDoublewidth divided by height.

YouVersionImageCollection has images ([YouVersionImage]), totalSize (Int?), and nextPageToken (String?).

Last modified on November 16, 2026
SearchReader Navigation and Toolbars
On this page
  • Images APIs
    • Overview
    • List images for a passage
    • Display an image
    • Verse of the Day art
    • Images in unified search
  • Parameters
    • Language ranges
    • Image fields
Swift
Swift
Swift
Swift
Swift