Bible SuperSearch API Documentation

Version 2.6.2

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 (By sending the CORS header: 'Access-Control-Allow-Origin: *')
  • 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
}

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 Finish 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,
    "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,
    "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": "2.6.2",
        "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: 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": "2.6.2",
        "environment": "production",
    }
}

Terms of Service

(Add your Terms of Service here)

Privacy Policy

(Add your Privacy Policy here)