Blessings API.
A meticulously crafted interface for accessing Biblical texts, supporting eleven translations with robust search and pericope retrieval.
Overview
The Blessings API is designed to provide immediate, programmatic access to Scripture. It is structured around REST principles, delivering lightweight, predictable JSON responses. CORS is fully enabled, allowing direct consumption from frontend applications.
- Retrieve precise single verses or expansive verse ranges.
- Search across a single translation or multiple translations concurrently.
- Filter results programmatically by specific book or testament.
- Access structural headings (pericopes) for contextual reading.
Translations
Eleven distinct translations are currently indexed, spanning English, Chinese, and Indonesian lexicons.
Single Verse
Retrieve a discrete verse by specifying the book, chapter, and verse integers.
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| translation | path | Required | Translation code (e.g., NIV). |
| book | query | Required | The title of the book (e.g., Genesis). |
| chapter | query | Required | Integer representing the chapter. |
| verse | query | Required | Integer representing the verse. |
{
"book": "Genesis",
"chapter": 1,
"verse": 1,
"content": "In the beginning God created the heavens and the earth."
}
Multiple Verses
Retrieve sequences or non-contiguous selections using a comma-separated list of textual references.
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| verses | query | Required | Comma-separated query string. E.g., Genesis 1:1-3,Matthew 1:1-25. |
Supported Notation Formats:
Single: Genesis 1:1
Range: Genesis 1:1-3
Cross-Chapter: Genesis 1:1-2:3
Full Chapter: Genesis 1
Pericope (Headings)
Extract the structural headings embedded within specific translations to contextualize readings.
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| book | query | Required | The target book name. |
| chapter | query | Optional | Target chapter. If omitted, returns headings for the entire book. |
Keyword Search
Perform a text search within a specific translation. Results include context highlighting.
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| keyword | query | Required | The term or phrase to locate. |
| limit | query | Optional | Maximum yield count. Defaults to 50. |
| book | query | Optional | Restrict search bounds to a single book. |
| testament | query | Optional | Filter bounds by old (or ot) or new (or nt). |
Multi-Translation Search
A powerful endpoint that parallelizes text queries across an array of requested translations.
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| keyword | query | Required | The term to search. |
| translations | query | Optional | Comma-separated list (e.g., NIV,ESV,KJV). Defaults to NIV. |
Implementation Examples
JavaScript
const fetchVerse = async () => {
const res = await fetch('http://api.blessings365.top/ESV/single?book=Psalms&chapter=23&verse=1');
const data = await res.json();
console.log(`${data.book} ${data.chapter}:${data.verse} — ${data.content}`);
};
fetchVerse();
Python
import requests
response = requests.get(
'http://api.blessings365.top/search',
params={'keyword': 'grace', 'translations': 'NIV,ESV', 'limit': 5}
)
print(response.json())
Error Handling
The API returns standard HTTP status codes indicating success or failure of a request.
| Code | Meaning | Resolution |
|---|---|---|
| 400 | Bad Request | Required parameters (like `keyword` or `book`) are missing. |
| 404 | Not Found | The specific verse, book, or translation does not exist in the index. |
| 500 | Server Error | Internal exception, often due to an unhandled parse error. |