Parse Bible References — JSON Bible API

The problem: inconsistent user input

Users never type Scripture references the same way twice. Your application must handle all of these:

john3:16 NIV Jn 3:16 rom 8:1-4,28 1 cor 13 Genisis ps 23 rev22:20-21

Without a normalization layer, your app must implement complex parsing logic — and still get it wrong on edge cases.

Why a simple parser is not enough

Many libraries detect references and produce OSIS strings like John.3.16. That solves display. It does not solve deterministic storage: you also need numeric book IDs, validated chapter/verse spans, and deduplication of compound ranges like Rom 8:1-4,28. The BibleBridge Scripture Resolver produces all of that in one request.

Resolve a reference

Send any human-written reference string. The Scripture Resolver handles abbreviations, verse carry-forward, book aliases, and compound ranges.

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

What the resolver does

Messy user input in → deterministic canonical coordinates out:

Normalization transform

Input

rom 8:1-4,28

john 3:16

→

Canonical output

book_id: 45 · spans: 8:1–4, 8:28

book_id: 43 · spans: 3:16

osis_id: Rom.8.1-Rom.8.4,Rom.8.28,John.3.16

Example response

{
  "type": "collection",
  "valid": true,
  "input": "rom 8:1-4,28; john 3:16",
  "osis_id": "Rom.8.1-Rom.8.4,Rom.8.28,John.3.16",
  "references": [
    {
      "type": "single",
      "valid": true,
      "book": { "key": "ROM", "book_id": 45, "name": "Romans", "slug": "romans" },
      "spans": [
        { "start": { "chapter": 8, "verse": 1 }, "end": { "chapter": 8, "verse": 4 } },
        { "start": { "chapter": 8, "verse": 28 }, "end": { "chapter": 8, "verse": 28 } }
      ],
      "osis_id": "Rom.8.1-Rom.8.4,Rom.8.28",
      "input_segments": [
        { "input": "rom 8:1-4,28", "normalized": "Romans 8:1-4, 28", "corrections": ["verse_carry", "book_alias"] }
      ]
    },
    {
      "type": "single",
      "valid": true,
      "book": { "key": "JHN", "book_id": 43, "name": "John", "slug": "john" },
      "spans": [
        { "start": { "chapter": 3, "verse": 16 }, "end": { "chapter": 3, "verse": 16 } }
      ],
      "osis_id": "John.3.16",
      "input_segments": [
        { "input": "john 3:16", "normalized": "John 3:16", "corrections": ["book_case_normalized"] }
      ]
    }
  ]
}

Response fields

Field	Description
osis_id	Canonical OSIS representation of the fully normalized reference
references[].book.book_id	Deterministic numeric book ID (1–66)
references[].spans[]	Explicit verse ranges after deduplication and normalization
input_segments[].normalized	Canonical human-readable reconstruction using the full book name
input_segments[].corrections	Tags: `verse_carry`, `book_alias`, `book_case_normalized`, `carry_forward`

Why this matters

Flexible input: accept human-written references from forms, chatbots, and user input

Deterministic output: normalize into stable canonical coordinates suitable for storage

Interoperability: generate OSIS identifiers compatible with many Bible systems

Foundation for traversal: canonical ranges feed directly into /expand, /context, and /scripture

Common use cases

Bible reading plan generators

AI Scripture retrieval systems

Search engines for biblical text

Church app sermon and notes backends

Try it yourself

Experiment interactively with flexible references in the Scripture Resolver Playground — no API key required.

Ready to normalize references?

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

Get a free API key Next: Expand references →

Normalize Flexible Scripture References