Next / Previous traversal using canonical Scripture references
Many Scripture applications require reliable navigation: “next verse”, “previous verse”, and smooth transitions across chapter boundaries. This example demonstrates a simple, production-safe approach using the BibleBridge API as a canonical text source while keeping navigation logic entirely in the client.
The API is used to retrieve chapter text by reference. Verse boundary detection and next/previous traversal are handled client-side based on the returned chapter data.
next_ref() and prev_ref() traversalIn production systems, chapters are typically cached to reduce repeat requests and improve speed.
This script starts at a reference and prints the next ten verses, automatically crossing chapter boundaries. It uses header-based authentication and canonical query parameters.
import os
import requests
API_BASE = "https://holybible.dev/api/scripture"
API_KEY = os.getenv("BIBLEBRIDGE_API_KEY")
if not API_KEY:
raise RuntimeError("Missing BIBLEBRIDGE_API_KEY. Set it as an environment variable.")
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def fetch_chapter(book_id, chapter, version):
r = requests.get(
API_BASE,
headers=HEADERS,
params={"bookID": book_id, "chapter": chapter, "version": version},
timeout=5
)
r.raise_for_status()
return r.json()
def chapter_verse_count(chapter_payload):
return len(chapter_payload["data"])
def next_ref(book_id, chapter, verse, version, cache):
key = (book_id, chapter, version)
if key not in cache:
cache[key] = fetch_chapter(book_id, chapter, version)
count = chapter_verse_count(cache[key])
if verse < count:
return (book_id, chapter, verse + 1)
next_key = (book_id, chapter + 1, version)
if next_key not in cache:
cache[next_key] = fetch_chapter(book_id, chapter + 1, version)
next_count = chapter_verse_count(cache[next_key])
if next_count == 0:
raise RuntimeError("No verses returned for next chapter.")
return (book_id, chapter + 1, 1)
def prev_ref(book_id, chapter, verse, version, cache):
if verse > 1:
return (book_id, chapter, verse - 1)
if chapter <= 1:
raise RuntimeError("At beginning of book. Implement book-to-book traversal if needed.")
prev_key = (book_id, chapter - 1, version)
if prev_key not in cache:
cache[prev_key] = fetch_chapter(book_id, chapter - 1, version)
prev_count = chapter_verse_count(cache[prev_key])
if prev_count == 0:
raise RuntimeError("No verses returned for previous chapter.")
return (book_id, chapter - 1, prev_count)
def get_verse_text(book_id, chapter, verse, version, cache):
key = (book_id, chapter, version)
if key not in cache:
cache[key] = fetch_chapter(book_id, chapter, version)
verses = cache[key]["data"]
if verse < 1 or verse > len(verses):
raise RuntimeError("Verse out of bounds for returned chapter data.")
return verses[verse - 1]["text"]
def run():
version = "KJV"
book_id = 20
chapter = 1
verse = 1
steps = 10
cache = {}
for i in range(steps):
text = get_verse_text(book_id, chapter, verse, version, cache)
print(f"Proverbs {chapter}:{verse} - {text}")
book_id, chapter, verse = next_ref(book_id, chapter, verse, version, cache)
if __name__ == "__main__":
run()
To run this example, set your API key as an environment variable named BIBLEBRIDGE_API_KEY.
For higher-volume traversal (larger books or repeated scans), a production API key is recommended.
Proverbs 1:1 - The proverbs of Solomon the son of David, king of Israel;
Proverbs 1:2 - To know wisdom and instruction; to perceive the words of understanding;
Proverbs 1:3 - To receive the instruction of wisdom, justice, and judgment, and equity;
Proverbs 1:4 - To give subtilty to the simple, to the young man knowledge and discretion.
Proverbs 1:5 - A wise man will hear, and will increase learning; and a man of understanding shall attain unto wise counsels:
Proverbs 1:6 - To understand a proverb, and the interpretation; the words of the wise, and their dark sayings.
Proverbs 1:7 - The fear of the LORD is the beginning of knowledge: but fools despise wisdom and instruction.
Proverbs 1:8 - My son, hear the instruction of thy father, and forsake not the law of thy mother:
Proverbs 1:9 - For they shall be an ornament of grace unto thy head, and chains about thy neck.
Proverbs 1:10 - My son, if sinners entice thee, consent thou not.
Canonical traversal is the foundation for readers, study tools, indexers, and Scripture-aware applications. By keeping traversal logic client-side, you maintain control over caching, pacing, and user experience while relying on the API for consistent Scripture retrieval.
For full endpoint details, see the BibleBridge API documentation.