Use the Images APIs to show verse art for the Verse of the Day, a search query, or a passage. This guide covers the Kotlin 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 Swift.
Images APIs
Overview
Use YouVersionApi.verseImages to find verse art for a passage and to load an image that search returns. The Images APIs need platform-core 2.7.0 or later. Configure the SDK with your app key as shown in the Quick Start.
Code
Each VerseImage has an imageUrl that you load with Coil, Glide, 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 suspend functions. pageSize must be from 1 through 99. Invalid inputs that the SDK checks throw IllegalArgumentException. Requests can also throw YouVersionNetworkException for an error response or a response the SDK cannot read, with a reason described in Error handling, and java.io.IOException when no response arrives.
Images methods
| Method | Returns | Use case |
|---|---|---|
verseImages | PaginatedResponse<VerseImage> | List images for a passage or language. passageId, languageRanges, pageSize, and pageToken are optional. |
verseImage(imageId) | VerseImage | The full record for an image id from search results or the Verse of the Day |
List images for a passage
verseImages(passageId) lists the art for a passage that you already know. To find art that matches freeform text, such as "love", use Page through image results 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 null nextPageToken means there are no more pages. If no images match, data is empty. totalSize is the number of matching images across all pages. It is set only when you pass passageId, and it is null otherwise.
Display an image
This example loads the image with Coil's AsyncImage. Coil 3 loads URLs only with a network artifact, and by default it saves every response to its disk cache, whatever the Cache-Control header says. To follow the caching rules, add the coil-network-cache-control artifact as well:
build.gradle.kts
If your app supports Android API 25 or lower, coil-network-cache-control also needs core library desugaring.
Your app also needs the android.permission.INTERNET permission in AndroidManifest.xml. Then give Coil an image loader that honors Cache-Control. Your Application class can provide it:
Code
Add a size to the image URL, reserve space with aspectRatio, and, if you want a credit line, show attribution with the image:
Code
VerseImage 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, pass a passage label as contentDescription or show nearby text from a Bible component. When equivalent verse text is already accessible, pass null so TalkBack skips the redundant art.
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 platform-core 2.8.0 or later.
Request the day's passage and selected image with verseOfTheDay(dayOfTheYear, languageRanges). Pass language ranges in order of preference. When the day has art, pass its imageId to verseImage(imageId):
Code
Pass the returned image to VerseImageCard from Display an Image. imageId is null 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.verseOfTheDays(languageRanges). It returns a list of YouVersionVerseOfTheDay records. See Images in Verse of the Day for language selection.
To find other art for the passage, use verseImages(passageId = votd.passageUsfm). 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 verseImages(passageId) when you already know the passage. To load a related image from unified search, pass its id to verseImage(imageId). The Search guide shows the request.
Parameters
Language ranges
For YouVersionApi.verseImages.verseImages, 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.
Kotlin callers often need these details:
- Use base language tags, such as
es. A regional tag such ases-MXreturns no results, and the ranges after it are not tried, solistOf("es-MX", "es")returns no results. - 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
listOf("*"), 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. |
imageUrl | String | 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. |
PaginatedResponse<VerseImage> has data (List<VerseImage>), totalSize (Int?), and nextPageToken (String?).