This project provides a REST API for semantic search of verses and passages from multiple Bible translations. Instead of keyword matches, it uses vector embeddings and similarity search to find passages related to a user's query. This allows developers to build applications that find relevant scripture from natural language sentences.
Note
The software is licensed under the MIT License. Bible texts, embeddings, and other imported datasets may be subject to separate licenses. This repository includes import scripts for public-domain translations. Users are responsible for ensuring they have the necessary rights to use and distribute any additional translations they import.
Traditional Bible APIs work well when the user is searching for a specific verse knowing what words appear in it, but they often struggle when the search is based on a broader concept, topic, or an approximate remembering of a verse. A user might search for "leadership", "anxiety", "mathematics", or even a sentence such as "That one passage about Jesus in Jerusalem". Relevant passages may not contain those exact words, causing conventional keyword searches to miss them. Vector Bible API is the solution to this problem.
See this project in action on my website at veskuvain.fi/bible.
Set environment variables in a local .env file (see .env_example), then run:
docker compose up --buildThe API will be available on http://localhost:8000.
docker compose run --rm app python scripts/thiagobodruk/import_fi_1776.pydocker compose run --rm app python scripts/thiagobodruk/import_en_kjv.pygetbible.net offers a plethora of other translations. Unfortunately, these translations must be downloaded manually, as scraping is not permitted. You can download a translation, for example, by running
curl -o scripts/data/[translation].json https://api.getbible.net/v2/[translation].jsonThis stores the translation in scripts/data/[translation].json. After that, run:
docker compose run --rm app python scripts/getbible/import_translation.py scripts/data/[translation].json [code] [name]This imports the translation into the database. By default, the script imports only the books that belong to the Protestant Canon. If the downloaded translation contains additional books and you want to include them as well, use the --no-canon-only option.
Get available translations at api.getbible.net/v2/translations.json.
docker compose run --rm app python scripts/embed_translation_chunks.py [translation]With chunk size of 5 and rolling window step of 2 as default. Can be customized with --chunk-size and
--window-step.
See documentation generated by FastAPI at http://localhost:8000/docs.
Example request:
GET http://localhost:8000/closest_matches/?query=Vectors%20and%20mathematics&translation=en_kjv&limit=3&offset=0&max_distance=0.85
Example response:
{
"query": "Vectors and mathematics",
"translation": "en_kjv",
"testament": null,
"book": null,
"limit": 3,
"offset": 0,
"max_distance": 0.85,
"matches": [
{
"book": "Ephesians",
"chapter": 3,
"verse": 18,
"text": "May be able to comprehend with all saints what {is} the breadth, and length, and depth, and height;",
"distance": 0.7563045658781126
},
{
"book": "Proverbs",
"chapter": 20,
"verse": 10,
"text": "Divers weights, {and} divers measures, both of them {are} alike abomination to the LORD. {Divers weights: Heb. A stone and a stone} {divers measures: Heb. an ephah and an ephah}",
"distance": 0.7636909902734879
},
{
"book": "1 Kings",
"chapter": 7,
"verse": 32,
"text": "And under the borders {were} four wheels; and the axletrees of the wheels {were joined} to the base: and the height of a wheel {was} a cubit and half a cubit. {joined...: Heb. in the base}",
"distance": 0.7648058233878677
}
]
}Example request:
GET http://localhost:8000/closest_chunks/?query=Jesus%20in%20Jerusalem&translation=en_kjv&testament=new&limit=1&offset=0&max_distance=0.75
Example response:
{
"query": "Jesus in Jerusalem",
"translation": "en_kjv",
"testament": "new",
"book": null,
"limit": 1,
"offset": 0,
"max_distance": 0.75,
"matches": [
{
"distance": 0.3868603939491686,
"verses": [
{
"book": "John",
"chapter": 11,
"verse": 54,
"text": "Jesus therefore walked no more openly among the Jews; but went thence unto a country near to the wilderness, into a city called Ephraim, and there continued with his disciples."
},
{
"book": "John",
"chapter": 11,
"verse": 55,
"text": "And the Jews' passover was nigh at hand: and many went out of the country up to Jerusalem before the passover, to purify themselves."
},
{
"book": "John",
"chapter": 11,
"verse": 56,
"text": "Then sought they for Jesus, and spake among themselves, as they stood in the temple, What think ye, that he will not come to the feast?"
},
{
"book": "John",
"chapter": 11,
"verse": 57,
"text": "Now both the chief priests and the Pharisees had given a commandment, that, if any man knew where he were, he should shew {it}, that they might take him."
},
{
"book": "John",
"chapter": 12,
"verse": 1,
"text": "Then Jesus six days before the passover came to Bethany, where Lazarus was which had been dead, whom he raised from the dead."
}
]
}
]
}| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query |
string | Yes | — | Natural language query |
translation |
string | Yes | — | Bible translation code (e.g. en_kjv, fi_1776) |
testament |
string | No | — | Testament from which to search (old, new) |
book |
string | No | — | Book from which to search |
limit |
integer | No | 5 | Maximum number of verse or chunk matches to return |
offset |
integer | No | 0 | Pagination offset |
max_distance |
float | No | 0.75 | Maximum vector distance (lower = results more similar to the query) |
The Bible texts used by this project come from two sources.
The King James Version (KJV) (en_kjv) and Biblia 1776 (fi_1776) are imported from the GitHub repository maintained by thiagobodruk. The import scripts included in this project are original and are used to import these public-domain translations.
Additional translations can be imported from getbible.net using the provided import script. As required by getbible.net, these translations must be downloaded manually before they can be imported into the database.
Many thanks to thiagobodruk for making these Bible texts available in a structured and accessible format, and to the maintainers of getbible.net for providing access to a wide range of Bible translations.