https://github.com/glowstudent777/youversion-api
Express Rest API for getting verses and such from YouVersion.
https://github.com/glowstudent777/youversion-api
api bible bible-api expressjs rest-api youversion
Last synced: 2 months ago
JSON representation
Express Rest API for getting verses and such from YouVersion.
- Host: GitHub
- URL: https://github.com/glowstudent777/youversion-api
- Owner: Glowstudent777
- License: mit
- Created: 2023-03-07T23:07:24.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-06-04T03:15:11.000Z (4 months ago)
- Last Synced: 2025-07-19T05:37:58.459Z (3 months ago)
- Topics: api, bible, bible-api, expressjs, rest-api, youversion
- Language: TypeScript
- Homepage:
- Size: 216 KB
- Stars: 72
- Watchers: 5
- Forks: 16
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# YouVersion-API
Express Rest API for getting verses and such from YouVersion.
# Cloning
Because this project uses submodules, you'll need to clone it with the `--recurse` flag.
```bash
git clone --recurse https://github.com/Glowstudent777/YouVersion-API.git && cd YouVersion-API
```
# Building and Running
> **Note**
> I use `pnpm` in these examples. `NPM` will also work if you don't have or want to install `pnpm`
```bash
pnpm i && pnpm run build
```
## Running
And to run use
```bash
pnpm run start
```
# Making Requests
| Query | Default | Required | Example |
| ------- | ------- | -------- | ----------- |
| book | None | true | John or JHN |
| chapter | 1 | false | 7 or 10 |
| verses | 1 | false | 1-3 or 7-10 |
| version | NIV | false | KJV or NLT |
## Examples
Gets `John 1:1 NIV`
```
https://serverAddress.com/api/v1/verse?book=John
```
Gets `John 3:16 NLT`
```
https://serverAddress.com/api/v1/verse?book=John&chapter=3&verses=16&version=NLT
```
---
## Responses
Requests return a JSON object and a status code.
### Good Responses
A good API call responds with a `200 OK` and the requested verse(s).
```json
{
"citation": "John 3:16 NLT",
"passage": "For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life."
}
```
Checking the API status is pretty simple, just make a request to the following route and if everything is fine it'll respond with a `200 OK` and no JSON object.
```
https://serverAddress.com/api/v1/status
```
### Bad Responses
If no book is specified in the query, it will prompt a `400 Bad Response` and an error message
```json
{
"code": 400,
"message": "Missing field 'book'"
}
```
Trying to access a book that does not exist will prompt a similar `400 Bad Response` but with a different error message
```json
{
"code": 400,
"message": "Could not find book 'Coffee' by name or alias."
}
```
# Options and Queries
Books and Aliases
| Book | Alias |
| ----------------- | ----- |
| Genesis | GEN |
| Exodus | EXO |
| Leviticus | LEV |
| Numbers | NUM |
| Deuteronomy | DEU |
| Joshua | JOS |
| Judges | JDG |
| Ruth | RUT |
| 1st Samuel | 1SA |
| 2nd Samuel | 2SA |
| 1st Kings | 1KI |
| 2nd Kings | 2KI |
| 1st Chronicles | 1CH |
| 2nd Chronicles | 2CH |
| Ezra | EZR |
| Nehemiah | NEH |
| Esther | EST |
| Job | JOB |
| Psalms | PSA |
| Proverbs | PRO |
| Ecclesiastes | ECC |
| Song of Songs | SNG |
| Isaiah | ISA |
| Jeremiah | JER |
| Lamentations | LAM |
| Ezekiel | EZK |
| Daniel | DAN |
| Hosea | HOS |
| Joel | JOL |
| Amos | AMO |
| Obadiah | OBA |
| Jonah | JON |
| Micah | MIC |
| Nahum | NAM |
| Habakkuk | HAB |
| Zephaniah | ZEP |
| Haggai | HAG |
| Zechariah | ZEC |
| Malachi | MAL |
| Matthew | MAT |
| Mark | MRK |
| Luke | LUK |
| John | JHN |
| Acts | ACT |
| Romans | ROM |
| 1st Corinthians | 1CO |
| 2nd Corinthians | 2CO |
| Galatians | GAL |
| Ephesians | EPH |
| Philippians | PHP |
| Colossians | COL |
| 1st Thessalonians | 1TH |
| 2nd Thessalonians | 2TH |
| 1st Timothy | 1TI |
| 2nd Timothy | 2TI |
| Titus | TIT |
| Philemon | PHM |
| Hebrews | HEB |
| James | JAS |
| 1st Peter | 1PE |
| 2nd Peter | 2PE |
| 1st John | 1JN |
| 2nd John | 2JN |
| 3rd John | 3JN |
| Jude | JUD |
| Revelation | REV |
Versions
| Versions | ID |
| -------- | ---- |
| AMP | 1588 |
| ICL00D | 1196 |
| KJV | 1 |
| NIV | 111 |
| NLT | 116 |
| NR06 | 122 |
| VULG | 823 |