Use the Images APIs to show verse art for the Verse of the Day, a search query, or a passage. This guide covers the JavaScript core SDK. For direct HTTP requests and the rules that apply to every platform, see Verse Images. For other SDKs, see the image guides for React, React Native Expo, Kotlin, and Swift.
Use ImagesClient from @youversion/platform-core to find verse art and load image metadata. These examples work in JavaScript and TypeScript applications.
Requirements
Use @youversion/platform-core 2.17.0 or later for all examples in this guide. Image listing and detail are available from 2.16.0; image search and VOTD image options require 2.17.0. Configure your app key as shown in the JavaScript SDK reference.
Code
List images for a passage
Create the clients and request one page of art:
Code
Replace YOUR_APP_KEY with your app key. The example logs a passage identifier and image URL for each image in the page.
getImages lists the art for a passage that you already know. Pass one verse or a verse range as passage_id. Chapter ids such as JHN.3 are unsupported. Omit language_ranges to include every language. See Language selection for the supported image-language filters.
Load another page
Pass next_page_token back as page_token, keeping the passage and language filters unchanged:
Code
Repeat when the user requests more results, using the token from each new page. A null token means there are no more pages. An empty page can still have a continuation token.
To find art that matches freeform text, such as "love", use image search instead.
Display a listed image
Use the image URL from a listed record. The following fragment selects the card size for the first record from the list above:
Code
Listing returns the full image record. Use getImage when you have an id from search or Verse of the Day.
Use URL.searchParams.set to select thumb, card, or full without removing query parameters from the original URL. Showing attribution as an image credit is optional; it can be empty. See Verse Images for rendition sizes and caching.
Load Verse of the Day art
Request the day's selected image by supplying language ranges, then resolve a non-null image_id:
Code
This requests January 1 and logs its passage identifier and the selected art URL. image_id 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 getAllVOTDs with the same language_ranges and read its data records. See Images in Verse of the Day for language selection.
Handle request failures
Client methods return promises and reject on invalid arguments, failed requests, or unreadable responses. For HTTP failures, import getHttpStatus from @youversion/platform-core and call getHttpStatus(error) to read the response status.
For parameter limits and response fields, see ImagesClient API.