Bible API

A small PHP API serving Bible passages, a Proverb of the Day, and YouVersion's Verse of the Day.

Endpoints

Unified API

Returns the chapter of Proverbs matching the current day of the month.

?version=esv&ref=potd
?version=esv&ref=potd&format=audio
?version=lxxsbl&ref=potd

Uses YouVersion's Verse of the Day reference.

?version=esv&ref=votd
?version=esv&ref=votd&format=audio
?version=htb&ref=votd
?version=sblgnt&ref=votd

Direct references use the same endpoint.

?version=esv&ref=john3:16
?version=svv&ref=John%203:16
?version=niv&ref=JHN.3.16
?version=brenton&ref=PSA.23.1
?version=sblgnt&ref=JHN.3.16

Westminster Standards

Westminster Confession and catechism references return the requested text and its Scripture-proof references from the local database:

?ref=wcf1.1
?ref=wsc1
?ref=wlc1
?version=esv&ref=wcf1.1

The version parameter is optional for these references. Omitting it skips all Bible lookups. Supplying esv, lxx, sblgnt, or lxxsbl appends every available proof passage. Proofs outside the selected text's coverage or missing from its source are marked unavailable without hiding the Westminster text or the other proofs. Expansion for the other externally hosted translations is not yet implemented.

ESV proof references are requested in a batch. Successful individual passages are cached for 10 minutes in data/passage_cache.sqlite to absorb refreshes. The disposable cache is excluded from Git, capped below the ESV API's storage limit, and evicts older entries as needed. Other versions can use separate cache policies when their provider rules have been reviewed.

NASB1995, NIV, NIVUK, TPT, and HTB proof passages are retrieved from YouVersion. Successful passages are cached only when YouVersion's response explicitly provides a positive Cache-Control: max-age; Age is deducted from that lifetime. Responses with no-cache, no-store, max-age=0, or no explicit cache lifetime are not stored.

?version=lxxsbl&ref=wsc1
?version=esv&ref=wsc1

The accepted parameters are version, ref, and optional format. Missing or unsupported parameters display this README. Ordinary Bible references require a supported version. Westminster references may omit it. An invalid Bible reference passed to a supported translation returns that translation backend's normal error.

USFM passage identifiers use forms such as:

JHN.3
JHN.3.16
JHN.3.16-18

Translation keys

Key Translation Source
esv English Standard Version ESV API
svv Statenvertaling Local public-domain SQLite
nasb1995 New American Standard Bible 1995 YouVersion
niv New International Version YouVersion
nivuk New International Version UK YouVersion
tpt The Passion Translation YouVersion
htb Het Boek YouVersion
brenton Brenton's English Septuagint Local public-domain SQLite
canisius Petrus Canisius Translation Local public-domain SQLite
lxx Septuagint in ancient Greek Local SQLite
sblgnt SBL Greek New Testament Local SQLite
lxxsbl LXX Old Testament and SBLGNT New Testament Local SQLite

Audio output is currently available only for ESV. Other translation keys fall back to text when format=audio is requested.

Scripture quotations marked “ESV” are from the ESV® Bible (The Holy Bible, English Standard Version®), © 2001 by Crossway, a publishing ministry of Good News Publishers. Used by permission. All rights reserved.

The supported format values are text, txt, html, and audio; the default is text, and txt is an alias for it. HTML and audio are currently available only for ESV.

References accept USFM codes, full English book names, common English abbreviations, and supported Dutch, Scottish Gaelic, and Greek aliases. Old Testament, New Testament, and Apocrypha names are maintained as separate reference registries.

Configuration

The external providers require these values in a local .env file:

ESV_API_KEY=
YVP_APP_KEY=

The .env file is ignored by Git and must not be committed.

The local Greek translations use data/greek_bible.sqlite and do not require an external API key.

The Westminster Standards use data/westminster.sqlite and do not require an external API key.

SVV, Brenton, and Canisius use data/public_domain_bibles.sqlite; they do not require external API keys or runtime passage caching. Source and rebuild details are documented in PUBLIC_DOMAIN_TEXTS.md.

Installation

The project requires PHP with cURL, PDO, and SQLite support.

Install the Markdown-rendering dependency from the committed lock file:

composer install

The document root must allow the supplied .htaccess rewrite rules.

Greek source data

data/greek_bible.sqlite is generated by cli/import_greek_bible.php. The downloaded cli/LXX/ and cli/SBLGNT/ source trees are intentionally excluded from Git.

Source details, licensing, attribution, and database record counts are documented in GREEK_TEXTS.md.