Common Integration Patterns

API.Bible can power many different types of applications—from full-featured Bible readers to simple Scripture embeds. This article highlights common integration patterns, explains how each works, and points out important implementation considerations so you can choose the approach that best fits your application.

What it is: A full browseable Bible experience where users can select a translation, navigate to a book and chapter, and read verse by verse.

How it works: This is a hierarchical pattern that moves through the API's structure step by step. A typical implementation begins by fetching the available Bibles (or a predefined subset), followed by books, chapters, verses, and finally the requested content.

Key considerations: This pattern generates a new API call each time a user navigates to new content, so caching is especially valuable here. Storing the chapter text locally after the first load means users can re-read the same content without consuming additional API calls. See Licensing Policies Quick Reference for caching rules.

Verse of the Day

What it is: A single curated verse displayed prominently on a homepage, app welcome screen, or daily email.

How it works: Your app fetches a specific verse by its Verse ID each day. The verse can be selected from a hardcoded schedule, a random selection from a curated list, or a third-party Verse of the Day feed. The verse content is fetched once and displayed until the next day's verse is due.

Key considerations: This is one of the most API-call-efficient patterns — you're making at most one request per day per verse. If multiple users see the same verse, caching it server-side means you only call the API once regardless of traffic. FUMS tracking is still required for each user who views the verse on a web interface.

Passage Display

What it is: A defined block of Scripture displayed as a unit — a sermon text, a devotional reading, a study passage, or a pericope embedded in an article.

How it works: Your app uses the Passage endpoint with a Passage ID defining the start and end verse (for example, ROM.8.1-ROM.8.11). The API returns all verses in that range as a single response, including the full text and a copyright notice. This is more efficient than fetching the same range verse by verse.

Key considerations: Passages are limited to 200 verses per request. If you need more, break the range into sequential chunks. For static passages that don't change (e.g., a fixed devotional reading), caching the response server-side eliminates repeat API calls entirely.

Scripture Search

What it is: A search bar where users can look up verses by keyword or passage reference — for example, "love" or "John 3:16."

How it works: Your app passes the user's query to the Search endpoint. For keyword searches, the API returns a list of matching verses. For passage references, it returns the passage content directly. Search results include basic verse text; if you need full formatted content for a result, make a follow-up verse or passage request using the returned Verse ID.

Key considerations: Each search request counts as one API call, regardless of how many results it returns. Keyword searches require all terms to be present in a matching verse. Wildcards (* and ?) are supported for partial-word matching.

Parallel Translation Comparison

What it is: The same verse or passage displayed side by side in two or more translations — useful for study tools, commentary apps, or translation comparison features.

How it works: There are two approaches. You can use the parallels parameter on a single verse request to receive additional translations in the same response. Or you can make separate verse requests for each Bible ID you want to compare and display the results together. Using the parallels parameter can reduce the number of API requests when retrieving the same passage across multiple translations.

Key considerations: Each Bible in a parallel view needs to be licensed on your plan. If you're requesting multiple Bibles separately, each request counts as its own API call. Caching each translation independently avoids re-fetching the same Bible content.

Embedded Scripture (Static or Curated)

What it is: Scripture woven into static content — a verse attached to a blog post, a Scripture reference in a sermon series page, or a memory verse in a curriculum module. The user doesn't choose what's displayed; the verse is pre-selected by the content author.

How it works: Your app fetches a specific verse or passage by its ID when the page loads. Because the content is fixed, the same API call is made every time that page is viewed — making server-side caching especially worthwhile. Alternatively, some teams pre-fetch and store verse content at publish time (subject to the applicable licensing and caching policies), eliminating runtime API calls altogether.

Key considerations: Even for embedded content that doesn't change, FUMS tracking is still required for web display. This can be done with a lightweight JavaScript call on page load — it doesn't require fetching the verse again.

A Note on Caching Across All Patterns

Caching is one of the most effective ways to reduce API call usage regardless of which pattern you're using. Here are the caching requirements:

Refresh cached content at least every 30 days
Do not cache more than 500 consecutive verses
Review the Licensing Policies Quick Reference for complete requirements