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
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
| Method | Returns | Use case |
|---|---|---|
images | YouVersionImageCollection | List images for a passage or language. passageID, languageRanges, pageSize, and pageToken are optional. |
image(id:) | YouVersionImage | The 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
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
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
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 ases-MXreturns 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, orzh-HK, notzh. - 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 omitlanguageRanges, to include every language.
This helper makes a range from the user's locale:
Code
Image fields
| Property | Type | Description |
|---|---|---|
id | String | The image id. |
url | URL | The URL of the image file. |
passageID | String | The verse or verse range that the image shows, such as JHN.3.16. |
attribution | String | The credit line for the image. Showing it is optional. |
languageTag | String | The language of the text on the art, such as en. |
width, height | Int | The original size in pixels. |
aspectRatio | Double | width divided by height. |
YouVersionImageCollection has images ([YouVersionImage]), totalSize (Int?), and nextPageToken (String?).