Scripture Resolver

Expand Scripture References into Verse Coordinates

Convert any normalized reference into explicit verse-level coordinates — stable identifiers ready for database indexing, traversal, and retrieval.

The problem

A reference like rom 8:1-4,28 represents five distinct verses. Without expansion, your app must manually calculate boundaries and enumerate each verse — which gets complicated fast across multi-range or cross-chapter references.

Expand a reference

Pass any reference string to /api/expand. The response contains every atomic verse coordinate in canonical order.

curl --get https://holybible.dev/api/expand \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode reference="rom 8:1-4,28"

How expansion works

One reference string fans out into 5 atomic verse coordinates:

rom 8:1-4,28

↓ /api/expand → 5 verse coordinates

Romans 8:1

verse_id: 45008001 · index: 28118

Romans 8:2

verse_id: 45008002 · index: 28119

Romans 8:3

verse_id: 45008003 · index: 28120

Romans 8:4

verse_id: 45008004 · index: 28121

8:5–27 skipped

Romans 8:28

verse_id: 45008028 · index: 28145

Example response

{
  "status": "success",
  "reference": "rom 8:1-4,28",
  "osis_id": "Rom.8.1-Rom.8.4,Rom.8.28",
  "verse_count": 5,
  "ranges": [
    { "range_start": 45008001, "range_end": 45008004 },
    { "range_start": 45008028, "range_end": 45008028 }
  ],
  "verse_ids":    [45008001, 45008002, 45008003, 45008004, 45008028],
  "verse_indexes":[28118, 28119, 28120, 28121, 28145],
  "data": [
    { "verse_id": 45008001, "verse_index": 28118, "book": "Romans", "chapter": 8, "verse": 1 },
    { "verse_id": 45008002, "verse_index": 28119, "book": "Romans", "chapter": 8, "verse": 2 },
    { "verse_id": 45008003, "verse_index": 28120, "book": "Romans", "chapter": 8, "verse": 3 },
    { "verse_id": 45008004, "verse_index": 28121, "book": "Romans", "chapter": 8, "verse": 4 },
    { "verse_id": 45008028, "verse_index": 28145, "book": "Romans", "chapter": 8, "verse": 28 }
  ]
}

Response fields

Field	Description
verse_count	Number of distinct verses in the reference
verse_ids	Deterministic numeric identifiers for each verse
verse_indexes	Global sequential positions within the 31,102-verse canon
data[].verse_id	Stable ID: `BBCCCVVV` (book · chapter · verse)
data[].verse_index	Global canonical position, usable with `/api/slice` and `/api/context`

Why this matters

Deterministic traversal: move forward or backward through Scripture using verse_index

Database indexing: store verse_id arrays in search engines or relational databases

AI context grounding: expand references into coordinates before fetching Scripture text for LLMs

Batch retrieval: convert complex compound references into predictable verse sets

Common use cases

Bible reading plan generators

Verse-by-verse navigation systems

Scripture search indexing pipelines

Biblical analytics and data processing

Ready to expand references?

A free API key gives you 500 calls per day — no credit card required.

Get a free API key Next: Retrieve context →