Bible SuperSearch API Documentation

Version 4.0.0

This API allows the Bible SuperSearch Bible search engine to be used seamlesly on any website or app.

There is no cost to use the API, however, a website will be limited to 1000 hits per day.


All API Actions:

  • Return a JSON-encoded string
  • Should be called using GET
  • Can be used cross-domain
  • Support JSONP via the 'callback' parameter
  • Return this basic structure:
{
    "errors": [],     // Array of error messages, if any.  If an error has occured, the API will return HTTP status code 400.
    "error_level": 0, // Integer indicating error level.  0 - No error, 1 & 2 - Reserved for future use, 3 - Non-fatal error,  4 - Fatal error 
    "results": {}     // Contains the actual data returned by the API
}

Linking Official Bible SuperSearch Applications to this API:



Bible SuperSearch

http://www.BibleSuperSearch.com
Bibles Available via API
Module* Language Name Short Name Year Copyrighted Research**
afri Afrikanns Afrikaans 1953 Afrikaans 1953 No No
svd Arabic Smith Van Dyke SVD No No
bkr Czech Bible Kralicka BKR No No
stve Dutch Staten Vertaling Stve No No
kjv English Authorized King James Version KJV 1611 / 1769 No No
bishops English Bishops Bible Bishops 1568 No No
coverdale English Coverdale Bible Coverdale 1535 No No
geneva English Geneva Bible Geneva 1587 No No
kjv_strongs English KJV with Strongs KJV Strongs 1611 / 1769 No No
tyndale English Tyndale Bible Tyndale No No
finn Finnish Finnish 1776 (Finnish) Finn 1776 No No
epee French La Bible de l'Épée Epee 2005 No No
martin French Martin Martin 1744 No No
oster French Ostervald Oster 1996 No No
luther German Luther Bible Luther 1545 No No
tr Greek Textus Receptus NT TR 1550 / 1884 No No
trparsed Greek Textus Receptus Parsed NT TR Parsed 1550 / 1884 No No
wlc Hebrew WLC Wlc No No
karoli Hungarian Karoli Karoli No No
diodati Italian Diodati Diodati 1649 No No
lith Lithuanian Lithuanian Bible Lith No No
maori Maori Maori Bible Maori No No
cornilescu Romanian Cornilescu Cornilescu No No
synodal Russian Synodal Synodal 1876 No No
rv_1858 Spanish Reina Valera 1858 NT RV 1858 1858 No No
rv_1909 Spanish Reina Valera 1909 RV 1909 1909 No No
rvg Spanish Reina Valera Gómez RVG 2010 Yes No
sagradas Spanish Sagradas Escrituras Sagradas 1569 No No
thaikjv Thai Thai KJV Thaikjv No No

* The 'module' is what the API uses to identify the Bible for queries.
** Indicates a Bible text that does not nessessarily adhere to the traditional Textus Receptus Greek and Masoretic Hebrew. These texts are intended for research purposes only.
Action: Query
URL: https://api.biblesupersearch.com/api
Description:Used for all queries against the Bibles in our database, including keyword searchs and passage retrieval.
When running a query, the only requirement is that either 'reference' or 'search' are required.

Examples

Look up Romans 4:1 - 10
https://api.biblesupersearch.com/api?bible=kjv&reference=Rom 4:1-10

Look up Rom 1:1-2; Matt 5:6-8; John 3:16
https://api.biblesupersearch.com/api?bible=kjv&reference=Rom 1:1-2; Matt 5:6-8; John 3:16

Search for 'faith'
https://api.biblesupersearch.com/api?bible=kjv&search=faith

'Romans' searched 'for faith'
https://api.biblesupersearch.com/api?bible=kjv&reference=Rom&search=faith

Jump to: Data Formats   Navigation   Pagination


Action Parameters
Parameter Name Type Default Description
reference Reference String (none) Passage reference, such as Romans 1:1-20; Acts 2:3; 1 Cor 5:20-6:7
search Search String (none) Keyword search
request Request String (none) Single field that can recieve either reference or keywords. If item resolves to a valid passage and specifies a chapter (or verse), request will be treated as a passage request; otherwise the request will be treated as a keyword search.
bible Bibles String
(Drop Down Menu - Multiple)
kjv MODULE of the Bible(s) to query against. Can be a string, array or JSON-encoded array.
Use the Bibles action to get a list of available Bibles for your app or website.
whole_words Whole Words Boolean false Whether to search for exact words. Otherwise, keywords will be found within words.
exact_case Exact Case Boolean false Whether to search for the exact case. Searches are case-insensitive by default.
data_format Data Format String passage Format of the outputed data structure.
  • 'minimal' or 'raw' format simply groups all verses by the Bible, and doesn't include book names.
  • 'passage' format groups verses into passages.
See examples below.
highlight Highlight Boolean false Whether to highlight keywords in retrieved verses. Setting this to 'true'
will cause highlight_tag to be wrapped around each matched keyword.
highlight_tag Highlight Tag String b HTML tag to use for wrapping highlighted keywords. Just set to the name of the tag, omitting <>
page Page Integer 1 For search results, the page to show. Currently, only searches support pagination.  See details below
page_all Show All Results Boolean false Whether to disable all pagination.
context Show in Context Boolean false For a given single verse, will return the verse with verses around it.
context_range Context Range Integer 5 Range of verses to pull when 'context' is true.
search_type Search Type String
(Drop Down menu)
and Type of search when using keyword search.
Options:
  • "and" or "all_words" - Searches for verses containing all words given.
  • "or" or "any_words" - Searches for verses containing any words given.
  • "xor" or "one_words" - Searches for verses containing only one word given.
  • "two_or_more" - Searches for two or more of the given keywords.
  • "keyword_limit" - Searches for two or more of the given keywords, with limit being changable via 'keyword_limit'.
  • "phrase" - Searches for verses containing the exact phrase given.
  • "boolean" - Searches for verses matching the boolean expression.
  • "regexp" - Searches for verses matching the regular expression.
  • "proximity" - Searches for words within 5 verses but not nessessarily in the same verse or chapter.
    This limit can be set via 'proximity_limit'
  • "chapter" - Searches for words within the same chapter but not nessessarily in the same verse.
  • "book" - Searches for words within the same book but not nessessarily in the same chapter or verse.
keyword_limit Keyword Limit Integer 5 Keyword limit. For 'keyword_limit' search type, sets the minimum number of keywords.
proximity_limit Proximity Limit Integer 5 Proximity limit. For Proximity search types, sets the range of allowable verses between keywords.
markup Markup Format String none Format of markup for Bibles having Strongs numbers or red letter.
'none' returns no markup.
'raw' returns the markup as stored in the database: {} indicates Strongs numbers, [] indicates added words, and ‹› (not <>) indicates red letter.
callback Call back String (none) Name of callback for JSONP, if needed

These advanced search fields can be used in addition to the standard ones above to build a powerful search interface:

Advanced Parameters
Parameter Name Type Default Description
search_all Search All String (none) For an advanced search form, this is the input for searching for all words.
search_any Search Any String (none) For an advanced search form, this is the input for searching for any words.
search_one Search One String (none) For an advanced search form, this is the input for searching for one of the words.
search_none Search None String (none) For an advanced search form, this is the input for searching for none of the words.
search_phrase Search Phrase String (none) For an advanced search form, this is the input for searching for an exact phrase.

Data Format Examples:

Reference: 'Rom 1:1-2; Matt 5:6-8'

'minimal' Data Structure:

Verses are grouped simply by Bible and ordered in the way they appear in the Bible. No book information is included.
{
    "errors":[],
    "error_level":0,
    "strongs":[], // If the search included any Strong's numbers, this array will contain the Strong's definition for each. See the "Strong's Definition" tab for details.
    "paging":{
        "total":338,
        "per_page":30,
        "current_page":1,
        "last_page":12,
        "from":1,
        "to":30
    },
    "results":{
        "kjv":[
            {"id":"23241","book":"40","chapter":"5","verse":"6","text":"Blessed are they which do hunger and thirst after righteousness: for they shall be filled."},
            {"id":"23242","book":"40","chapter":"5","verse":"7","text":"Blessed are the merciful: for they shall obtain mercy."},
            {"id":"23243","book":"40","chapter":"5","verse":"8","text":"Blessed are the pure in heart: for they shall see God."},
            {"id":"27932","book":"45","chapter":"1","verse":"1","text":"Paul, a servant of Jesus Christ, called to be an apostle, separated unto the gospel of God,"},
            {"id":"27933","book":"45","chapter":"1","verse":"2","text":"(Which he had promised afore by his prophets in the holy scriptures,)"}
        ]
    }
}

'passage' Data Structure:

Verses are grouped into passages, and passages are ordered in the order they were requested by the user.
{
    "errors":[],
    "error_level":0,
    "strongs":[], // If the search included any Strong's numbers, this array will contain the Strong's definition for each. See the "Strong's Definition" tab for details.
    "results":[
        {
            "book_id":45,
            "book_name":"Romans",
            "book_short":"Rm",
            "book_raw":"Rom",            // Book name as entered by user
            "chapter_verse":"1:1-2",     // Standardized chapter and verse
            "nav":{ ... },               // Metadata for browsing buttons, see below for details
            "chapter_verse_raw":"1:1-2", // Chapter and verse as entered by user
            "verse_index": {             // A list of all chapters and verses retrieved.
                1: [1, 2]
            },
            "verses":{
                // Indexed by Bible (module)
                "kjv":{
                    // Indexed by chapter
                    "1":{
                        // Indexed by verse
                        "1":{"id":"27932","book":"45","chapter":"1","verse":"1","text":"Paul, a servant of Jesus Christ, called to be an apostle, separated unto the gospel of God,"},
                        "2":{"id":"27933","book":"45","chapter":"1","verse":"2","text":"(Which he had promised afore by his prophets in the holy scriptures,)"}
                    }
                }
            },
            "verses_count":2,
            "single_verse":false  // Indicates if the passage contains exactly one verse.  Note: Searches will result in all single verse passages.
        },
        {
            "book_id":40,
            "book_name":"Matthew",
            "book_short":"Mt",
            "book_raw":"Matt",
            "chapter_verse":"5:6-8",
            "chapter_verse_raw":"5:6-8",
            "nav": {ncb: 40, ncc: 6, pcb: 40, pcc: 4, ccb: 40, ccc: 5, nb: 41, pb: 39}
            "verse_index": {
                5: [6, 7, 8]
            },
            "verses":{
                "kjv":{
                    "5":{
                        "6":{"id":"23241","book":"40","chapter":"5","verse":"6","text":"Blessed are they which do hunger and thirst after righteousness: for they shall be filled."},
                        "7":{"id":"23242","book":"40","chapter":"5","verse":"7","text":"Blessed are the merciful: for they shall obtain mercy."},
                        "8":{"id":"23243","book":"40","chapter":"5","verse":"8","text":"Blessed are the pure in heart: for they shall see God."}
                    }
                }
            },
            "verses_count":3,
            "single_verse":false
        }
    ]
}


Navigation

Book Browsing

For multiverse ranges and chapters, this gives the book and chapter metadata for generating browsing buttons. Only available on 'passage' data structures and is not currently provided for single verses.

{
    "errors":[],
    "error_level":0,
    "results":[
        {
            "book_id":40,
            "book_name":"Matthew",
            "book_short":"Mt",
            "book_raw":"Matt",
            "chapter_verse":"5:6-8",
            "chapter_verse_raw":"5:6-8",
            "nav": {
                // Link to Next Chapter, if applicable
                next_chapter: "Matthew 6",  // 'reference' for next chapter link
                ncb: 40,    // Next chapter book: book_id of the chapter following this one
                ncc: 6,     // Next chapter chapter: chapter number of chapter following this one

                // Link to Previous Chapter, if applicable
                prev_chapter: "Matthew 4",  // 'reference' for previous chapter link
                pcb: 40,    // Previous chapter book: book_id of the chapter preceding this one
                pcc: 4,     // Previous chapter chapter: chapter number of the chapter preceding this one

                // Link to current chapter (if not already displaying the whole chapter)
                cur_chapter: "Matthew 5",   // 'reference' for current chapter link
                ccb: 40,    // Current chapter book: book_id of the current chapter
                ccc: 5,     // Current chapter chapter: chapter number of the current chapter,

                // Link to the Next Book, if applicable
                next_book: "Mark",          // 'reference' of next book
                nb: 41,     // Book_id of the next book

                // Link to the Previous Book, if applicable
                prev_book: "Malachi"        // 'reference' of previous book
                pb: 39      // Book_id of the previous book
            },
            "verse_index": {
                5: [6, 7, 8]
            },
            "verses":{ ... }
            "verses_count":3,
            "single_verse":false
        }
    ]
}

Search Pagination

For all searches, this provides the metadata for building pagination. (Please note, setting 'page_all' to true disables all pagination),

{
    "errors":[],
    "error_level":0,
    "paging":{
        "total":338,        // Total number of results
        "per_page":30,      // Results per page
        "current_page":1,   // Current page number
        "last_page":12,     // Total number of pages
        "from":61,          // First displaying result  Example: 'Now displaying results 61 to 90'
        "to":90             // Last displaying result
    },
    "results":[ ... ]
}
Action: Statics
URL: https://api.biblesupersearch.com/api/statics
Description:Single API action to retrieve basic information needed to use the API.

This includes:
  • A list of all avaliable Bibles
  • A list of Bible books in the specified language
  • A list of shortcuts in the specified language
  • A list of search types
  • The API name
  • The API version
  • The API environment (production/beta/development)

Action Parameters
Parameter Name Type Default Description
language Language String en 2 Character ISO 639‑1 language code
callback Call back String (none) Name of callback for JSONP, if needed

Data Structure Example:
{
    "errors": [],
    "error_level": 0,
    "results": {
        "bibles": { ... }, // See Bibles Action
        "books": [ ... ],  // See Books Action
        "search_types": [ ... ],
        "shortcuts": [ ... ],
        "name": "Bible SuperSearch API",
        "version": "4.0.0",
        "environment": "production",
    }
}
Action: Bibles
URL: https://api.biblesupersearch.com/api/bibles
Description:Retrieves the list of Bibles avaliable via the API

Action Parameters
Parameter Name Type Default Description
callback Call back String (none) Name of callback for JSONP, if needed

Data Structure Example:
{
    "errors":[],
    "error_level":0,
    "results":{
        // Indexed by 'module'
        "kjv":{
            "name":"Authorized King James Version",
            "shortname":"KJV",
            "module":"kjv",         // The 'module' is what the API uses to identify the Bible for queries.
            "year":"1611 \/ 1769",  // Publication year
            "lang":"English",
            "lang_short":"en",
            "copyright":"0",        // Copyrighted (not public domain)
            "italics":"1",          // (Future use) Supports Italicised words 
            "strongs":"0",          // (Future use) Embedded strongs numbers
            "rank":"10",            // Default sorting order.
            "research":"0"          // Indicates a Bible text intended for research purposes only.
        },
        "geneva":{
            "name":"Geneva Bible",
            "shortname":"Geneva",
            "module":"geneva",
            "year":"1587",
            "lang":"English",
            "lang_short":"en",
            "copyright":"0",
            "italics":"0",
            "strongs":"0",
            "rank":"60",
            "research":"0"
        },
        "tr":{
            "name":"Textus Receptus NT",
            "shortname":"TR","
            "module":"tr",
            "year":"1550 \/ 1884",
            "lang":"Greek",
            "lang_short":"el","
            copyright":"0",
            "italics":"0",
            "strongs":"0",
            "rank":"70",
            "research":"0"
        },
        "wlc":{
            "name":"WLC",
            "shortname":"Wlc",
            "module":"wlc",
            "year":"",
            "lang":"Hebrew",
            "lang_short":"he",
            "copyright":"0",
            "italics":"0",
            "strongs":"0",
            "rank":"300",
            "research":"1"
        }
    }
}
Action: Books
URL: https://api.biblesupersearch.com/api/books
Description:Retrieves a list of Bible Books in the specified language

Action Parameters
Parameter Name Type Default Description
language Language String en 2 Character ISO 639‑1 language code
callback Call back String (none) Name of callback for JSONP, if needed

Data Structure Example:
{
    "errors":[],
    "error_level":0,
    "results":[
        {"id":1,"name":"Genesis","shortname":"Gen"},
        {"id":2,"name":"Exodus","shortname":"Ex"},
        ....
        {"id":65,"name":"Jude","shortname":"Jude"},
        {"id":66,"name":"Revelation","shortname":"Rev"}
    ]
}
Action: Strong's Definition
URL: https://api.biblesupersearch.com/api/strongs
Description:Retrieves definitions for the given Strong's numbers.

Action Parameters
Parameter Name Type Default Description
strongs Strong's Number(s) String (none) Retrieve Strong's definitions for the given Strong's numbers. Can be a single string, a comma-separated string or a JSON-encoded array
callback Call back String (none) Name of callback for JSONP, if needed

Data Structure Example:
Note: Some Strong's numbers will return TVM (Tense / Voice / Mood) records. Your app will need to be able to handle both.
{
    "errors":[],
    "error_level":0,
    "results":[
        // Definition record, "tvm" will be empty.
        {
            "id":11398,
            "number":"G2545",
            "root_word":"καίω",
            "transliteration":"kaiō",
            "pronunciation":"kah'-yo",
            "tvm":"",
            "entry":"Apparently a primary verb; to <i>set on fire<\/i>, that is, <i>kindle<\/i>  or (by implication) <i>consume:<\/i>  - burn, light."
        },
        // TVM record, "tvm" will be populated, and other items will be empty.
        {
            "id":14471,
            "number":"G5719",
            "root_word":null,
            "transliteration":null,
            "pronunciation":null,
            "tvm":"<b>Tense:<\/b> Present, See G5774 <br><b>Voice:<\/b> Active, See G5784 <br><b>Mood:<\/b> Indicative, See G5791 <br>\n",
            "entry":null
        }
    ]
}
Action: Version
URL: https://api.biblesupersearch.com/api/version
Description:Retrieves basic version information about the API.

This includes:
  • The API name
  • The API version
  • The API environment (production/beta/development)

Action Parameters
Parameter Name Type Default Description
callback Call back String (none) Name of callback for JSONP, if needed

Data Structure Example:
{
    "errors": [],
    "error_level": 0,
    "results": {
        "name": "Bible SuperSearch API",
        "version": "4.0.0",
        "environment": "production",
    }
}

Terms of Service

By using the Bible SuperSearch API ("service", "API"), you agree to the terms of this agreement between yourself ("customer") and Preserved Word Ministries ("we", "our", "us") (Bible SuperSearch is a ministry of Preserved Word Ministries).

We reserve the right to limit access to the service.  We reserve the right to discontinue the service at any time.  

The Bible SuperSearch API and client software are licensed for NON-COMMERCIAL usage ONLY.   Any commercial usage requires our prior expressed written permission.

Support

While we offer free access to the API, support will require the the purchase of a support license.   We can only offer support for the API located at https://api.biblesupersearch.com.   We are unable to provide support for any of our sandbox APIs, nor for instances of our API hosted by a third party.   While the code for this API is Open Source and can be downloaded and installed from our GIT repository, we cannot provide support for this at this time.

Returns

All sales are final on support licenses, software, and software enhancements.

No Warranty

This service is made available in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Limitation of Liability

In no event shall Preserved Word Ministries, nor any of its officers, directors and employees, be liable to you for anything arising out of or in any way connected with your use of this service, whether such liability is under contract, tort or otherwise, and Preserved Word Ministries, including its officers, directors and employees shall not be liable for any indirect, consequential or special liability arising out of or in any way related to your use of this service.

Indemnification

You hereby indemnify to the fullest extent Preserved Word Ministries from and against any and all liabilities, costs, demands, causes of action, damages and expenses (including reasonable attorney’s fees) arising out of or in any way related to your breach of any of the provisions of these Terms.

Prohibited Usage

We reserve the right to terminate a customer's access to the service for any usage we deem to be an abuse, including but not limited to the following:
  • Attempting to circumvent the daily access limit.
  • Reselling access to the service, or acting a relay or proxy between the API and a third party.
  • Use for any commercial purpose (such as inclusion behind a paid access login), without our prior expressed written permission.
  • Providing API access keys, if any, to a third party.
  • Using the service in any way to impact the access of other users.
  • Using the service to demean, vilify or blaspheme God, Jesus Christ, the Holy Spirit or the Bible itself.

Severability

If any provision of these Terms is found to be unenforceable or invalid under any applicable law, such unenforceability or invalidity shall not render these Terms unenforceable or invalid as a whole, and such provisions shall be deleted without affecting the remaining provisions herein.

Variation of Terms

Preserved Word Ministries is permitted to revise these Terms at any time as it sees fit, and by using this service you are expected to review such Terms on a regular basis to ensure you understand all terms and conditions governing use of this service.

Governing Law and Jurisdiction

This agreement shall be governed pursuant to the laws of the state of Michigan.