{ "openapi" : "3.0.3", "info" : { "version" : "2.8", "title" : "BibleGet", "description" : "Get Bible quotes from different Bible versions either requesting by reference (book - chapter - verse) or searching by keyword", "license" : { "name" : "Apache 2.0", "url" : "http://www.apache.org/licenses/LICENSE-2.0" }, "termsOfService" : "https://www.bibleget.io/BibleGetIOTermsofService.html", "contact" : { "name" : "John D'Orazio", "url" : "https://www.bibleget.io", "email" : "admin@bibleget.io" } }, "servers" : [ { "url" : "https://query.bibleget.io" } ], "paths" : { "/index.php" : { "get" : { "summary" : "Retrieve Bible quotes by reference (book - chapter - verse)", "description" : "The API endpoint from which one can retrieve Bible quotes by reference (book - chapter - verse)", "operationId" : "getVersesByGET", "tags" : [ "MainAPI" ], "parameters" : [ { "$ref" : "#/components/parameters/query" }, { "$ref" : "#/components/parameters/version" }, { "$ref" : "#/components/parameters/return" }, { "$ref" : "#/components/parameters/appid" }, { "$ref" : "#/components/parameters/pluginversion" }, { "$ref" : "#/components/parameters/domain" } ], "responses" : { "200" : { "description" : "Structured data containing the Bible verses requested and all associated information", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BibleQuoteJSON" } }, "application/xml" : { "schema" : { "$ref" : "#/components/schemas/BibleQuoteXML" } }, "text/html" : { "schema" : { "$ref" : "#/components/schemas/BibleQuoteJSON" } } } } } }, "post" : { "summary" : "Retrieve Bible quotes by reference (book - chapter - verse)", "description" : "The API endpoint from which one can retrieve Bible quotes by reference (book - chapter - verse)", "operationId" : "getVersesByPOST", "tags" : [ "MainAPI" ], "requestBody" : { "content" : { "application/x-www-form-urlencoded" : { "schema" : { "$ref" : "#/components/schemas/BibleQuotePOST" }, "encoding" : { "version" : { "style" : "form", "explode" : false } } } } }, "responses" : { "200" : { "description" : "Structured data containing the Bible verses requested and all associated information", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BibleQuoteJSON" } }, "application/xml" : { "schema" : { "$ref" : "#/components/schemas/BibleQuoteXML" } }, "text/html" : { "schema" : { "$ref" : "#/components/schemas/BibleQuoteJSON" } } } } } } }, "/metadata.php" : { "get" : { "summary" : "Retrieve metadata about Bible versions that are available and their relative book/chapter/verse indexes", "description" : "The API endpoint for querying metadata such as Bible versions that are available and their relative book/chapter/verse indexes. **N.B. Applications or plugins should CACHE the information returned by the METADATA endpoint. This data does not change often, there is no need to request it for every Bible quote requested from the main API endpoint. It can be a good idea to refresh this information about, let's say once a month, or create a user interface with a button that will allow the end user to refresh the information from the server if they think the cached information might be old.**", "operationId" : "getMetadataByGET", "tags" : [ "MetadataAPI" ], "parameters" : [ { "name" : "query", "in" : "query", "description" : "Specifies the subset of metadata to retrieve. **`biblebooks`**: retrieve the list of valid **book names** and **abbreviations** in various languages that are currently supported / recognized by the main BibleGet API endpoint. **`bibleversions`**: retrieve the list of **Bible versions** that are currently supported by the main BibleGet API endpoint. **`versionindex`**: retrieve the **indices of chapters and verses** for any of the Bible versions currently supported by the BibleGet engine (this value requires the usage of a second parameter `versions`).", "required" : true, "schema" : { "type" : "string", "enum" : [ "biblebooks", "bibleversions", "versionindex" ] }, "examples" : { "biblebooks" : { "summary" : "Retrieve the list of valid book names and abbreviations in various languages that are currently supported / recognized by the main BibleGet API endpoint", "value" : "biblebooks" }, "bibleversions" : { "summary" : "Retrieve the list of Bible versions that are currently supported by the main BibleGet API endpoint.", "value" : "bibleversions" }, "versionindex" : { "summary" : "Retrieve the **indices of chapters and verses** for any of the Bible versions currently supported by the BibleGet engine. Requires the usage of a second parameter `versions`.", "value" : "versionindex" } } }, { "name" : "versions", "in" : "query", "description" : "*(required in the case of a `query=versionindex` request)* Indicates for which Bible versions the indices data should be returned. The acronyms for valid Bible versions as returned by `query=bibleversions` should be used, either as a single string value or as a comma separated list of values.", "required" : false, "schema" : { "type" : "array", "items" : { "type" : "string" }, "default" : [ "CEI2008" ] }, "style" : "form", "explode" : false, "examples" : { "singleVersion" : { "summary" : "Single Bible version", "value" : [ "NABRE" ] }, "multipleVersions" : { "summary" : "Multiple Bible versions", "value" : [ "NABRE", "NVBSE" ] } } }, { "name" : "return", "in" : "query", "description" : "Type of data that should be returned in the response", "required" : false, "schema" : { "type" : "string", "enum" : [ "json", "xml", "html" ], "default" : "json" }, "examples" : { "json" : { "summary" : "Request that the data be returned in JSON format", "value" : "json" }, "xml" : { "summary" : "Request that the data be returned in XML format", "value" : "xml" }, "html" : { "summary" : "Request that the data be returned in HTML format", "value" : "html" } } } ], "responses" : { "200" : { "description" : "Structured data containing the required metadata about either Bible versions available, Bible version indexes, or the names and abbreviations of Bible books for any given Bible version", "content" : { "application/json" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/MetadataBibleVersions" }, { "$ref" : "#/components/schemas/MetadataBibleBooks" }, { "$ref" : "#/components/schemas/MetadataVersionIndex" } ] } }, "application/xml" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/MetadataBibleVersions" }, { "$ref" : "#/components/schemas/MetadataBibleBooks" }, { "$ref" : "#/components/schemas/MetadataVersionIndex" } ] } }, "text/html" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/MetadataBibleVersions" }, { "$ref" : "#/components/schemas/MetadataBibleBooks" }, { "$ref" : "#/components/schemas/MetadataVersionIndex" } ] } } } } } }, "post" : { "summary" : "Retrieve metadata about Bible versions that are available and their relative book/chapter/verse indexes", "description" : "The API endpoint for querying metadata such as Bible versions that are available and their relative book/chapter/verse indexes", "operationId" : "getMetadataByPOST", "tags" : [ "MetadataAPI" ], "requestBody" : { "content" : { "application/x-www-form-urlencoded" : { "schema" : { "type" : "object", "properties" : { "query" : { "type" : "string", "description" : "Specifies the subset of metadata to retrieve. **`biblebooks`**: retrieve the list of valid **book names** and **abbreviations** in various languages that are currently supported / recognized by the main BibleGet API endpoint. **`bibleversions`**: retrieve the list of **Bible versions** that are currently supported by the main BibleGet API endpoint. **`versionindex`**: retrieve the **indices of chapters and verses** for any of the Bible versions currently supported by the BibleGet engine (this value requires the usage of a second parameter `versions`).", "enum" : [ "biblebooks", "bibleversions", "versionindex" ], "example" : "bibleversions" }, "versions" : { "type" : "array", "description" : "Bible version or versions from which to retrieve the Bible quote. A list of valid versions can be retrieved from the `metadata.php` API using `query=bibleversions`", "items" : { "type" : "string" }, "example" : [ "NABRE", "NVBSE" ], "default" : [ "CEI2008" ] }, "return" : { "type" : "string", "description" : "Type of data that should be returned in the response", "enum" : [ "json", "xml", "html" ], "example" : "json", "default" : "json" } }, "required" : [ "query" ] }, "encoding" : { "versions" : { "style" : "form", "explode" : false } } } } }, "responses" : { "200" : { "description" : "Structured data containing the required metadata about either Bible versions available, Bible version indexes, or the names and abbreviations of Bible books for any given Bible version", "content" : { "application/json" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/MetadataBibleVersions" }, { "$ref" : "#/components/schemas/MetadataBibleBooks" }, { "$ref" : "#/components/schemas/MetadataVersionIndex" } ] } }, "application/xml" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/MetadataBibleVersions" }, { "$ref" : "#/components/schemas/MetadataBibleBooks" }, { "$ref" : "#/components/schemas/MetadataVersionIndex" } ] } }, "text/html" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/MetadataBibleVersions" }, { "$ref" : "#/components/schemas/MetadataBibleBooks" }, { "$ref" : "#/components/schemas/MetadataVersionIndex" } ] } } } } } } }, "/search.php" : { "get" : { "summary" : "Search for Bible verses that contain a given keyword. In the future, search by topic may also be implemented.", "description" : "The API endpoint for performing search queries for Bible verses by keyword (or topic).", "operationId" : "searchVersesByGET", "tags" : [ "SearchAPI" ], "parameters" : [ { "name" : "query", "in" : "query", "description" : "Specifies the kind of search to perform. As of v2.8 of the search API only a value of `keywordsearch` is available.", "required" : true, "schema" : { "type" : "string", "enum" : [ "keywordsearch" ] }, "examples" : { "keywordsearch" : { "summary" : "Perfom a search for Bible verses that contain the indicated keyword. Requires the usage of a second parameter: keyword. As of v2.8 of the search API endpoint, Search by topic is not yet available.", "value" : "keywordsearch" } } }, { "name" : "keyword", "in" : "query", "description" : "*(required when making a request where `query=keywordsearch`)* indicates the keyword that will be searched in the text of the Bible verses", "schema" : { "type" : "string" }, "examples" : { "creation" : { "summary" : "Perform a search for Bible verses that contain the keyword 'creation'.", "value" : "creation" } } }, { "name" : "version", "in" : "query", "description" : "The acronym of the Bible version within which to perform the search by keyword. Can only be a single value, not a comma delimited list of values.", "required" : true, "schema" : { "type" : "string" }, "examples" : { "NABRE" : { "summary" : "perform a search for Bible verses containing a given keyword in the *NABRE* Bible version.", "value" : "NABRE" }, "NVBSE" : { "summary" : "perform a search for Bible verses containing a given keyword in the *NVBSE* Bible version.", "value" : "NVBSE" } } }, { "name" : "exactmatch", "in" : "query", "description" : "since the default behaviour for a keyword search is to find any word of 4 or more letters which matches or contains the keyword, this option will try to find only exact matches and will also allow to search for words of even only 3 letters (parts of speech excluded)", "required" : false, "schema" : { "type" : "boolean" }, "examples" : { "true" : { "summary" : "find only exact matches of words that are made up of 3 or more letters (parts of speech excluded)", "value" : "true" }, "false" : { "summary" : "find both exact and partial matches of words made up of 4 or more letters", "value" : "false" } } }, { "name" : "return", "in" : "query", "description" : "Type of data that should be returned in the response", "required" : false, "schema" : { "type" : "string", "enum" : [ "json", "xml", "html" ], "default" : "json" }, "examples" : { "json" : { "summary" : "Request that the data be returned in JSON format", "value" : "json" }, "xml" : { "summary" : "Request that the data be returned in XML format", "value" : "xml" }, "html" : { "summary" : "Request that the data be returned in HTML format", "value" : "html" } } } ], "responses" : { "200" : { "description" : "", "content" : { "application/json" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/KeywordSearchJSON" } ] } }, "application/xml" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/KeywordSearchXML" } ] } }, "application/html" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/KeywordSearchJSON" } ] } } } } } }, "post" : { "summary" : "Search for Bible verses that contain a given keyword. In the future, search by topic may also be implemented.", "description" : "The API endpoint for performing search queries for Bible verses by keyword (or topic).", "operationId" : "searchVersesByPOST", "tags" : [ "SearchAPI" ], "requestBody" : { "content" : { "application/x-www-form-urlencoded" : { "schema" : { "type" : "object", "properties" : { "query" : { "type" : "string", "description" : "Specifies the kind of search to perform. As of v2.8 of the search API only a value of `keywordsearch` is available.", "enum" : [ "keywordsearch" ], "example" : "keywordsearch" }, "keyword" : { "type" : "string", "description" : "*(required when `query=keywordsearch`)* indicates the keyword that will be searched in the text of the Bible verses", "example" : "creation" }, "version" : { "type" : "string", "description" : "The acronym of the Bible version within which to perform the search by keyword. Can only be a single value, not a comma delimited list of values.", "example" : "NVBSE" }, "exactmatch" : { "type" : "boolean", "description" : "since the default behaviour for a keyword search is to find any word of 4 or more letters which matches or contains the keyword, this option will try to find only exact matches and will also allow to search for words of even only 3 letters (parts of speech excluded)", "example" : "true" }, "return" : { "type" : "string", "description" : "Type of data that should be returned in the response", "enum" : [ "json", "xml", "html" ], "example" : "json", "default" : "json" } }, "required" : [ "query", "version" ] } } } }, "responses" : { "200" : { "description" : "", "content" : { "application/json" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/KeywordSearchJSON" } ] } }, "application/xml" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/KeywordSearchXML" } ] } }, "application/html" : { "schema" : { "oneOf" : [ { "$ref" : "#/components/schemas/KeywordSearchJSON" } ] } } } } } } } }, "components" : { "schemas" : { "BibleQuotePOST" : { "type" : "object", "properties" : { "query" : { "type" : "string", "description" : "Bible reference using standard Bible citation notation.", "example" : "Genesis1:1-10" }, "version" : { "type" : "array", "description" : "Bible version or versions from which to retrieve the Bible quote. A list of valid versions can be retrieved from the `metadata.php` API using `query=bibleversions`", "items" : { "type" : "string" }, "example" : [ "NABRE", "NVBSE" ] }, "return" : { "type" : "string", "description" : "Type of data that should be returned in the response", "enum" : [ "json", "xml", "html" ], "example" : "json", "default" : "json" }, "appid" : { "type" : "string", "description" : "Unique identifier of the application making the request, to be agreed upon with the owner of the API endpoint", "example" : "swaggerhub" }, "pluginversion" : { "type" : "string", "description" : "Version number of the application making the request. Useful not only for statistics, to help understand which version of an application is being actively used, but also (especially in the case of the official applications) to help deal with possibly breaking changes between the application version and versions of the API endpoint", "example" : "v1.0" }, "domain" : { "type" : "string", "description" : "In the case of web based applications, should indicate the domain from which the request is generated. Currently used by the official plugin for WordPress to better understand usage of the plugin and monitor requests. When the application or plugin making the request can be installed on different domains (as is the case with the WordPress plugin), this value should be generated dynamically from a server variable identifying the domain. If instead it will always be the same domain making the requests, the value can be hardcoded with the actual domain.", "example" : "app.swaggerhub.com" } }, "required" : [ "query", "version", "appid" ] }, "BibleQuoteJSON" : { "type" : "object", "properties" : { "results" : { "type" : "array", "description" : "Array of objects each of which represents a Bible verse with all associated information", "items" : { "type" : "object", "properties" : { "testament" : { "type" : "integer", "enum" : [ 1, 2 ], "description" : "`1` = *Old Testament*, `2` = *New Testament*", "xml" : { "attribute" : true } }, "section" : { "type" : "integer", "enum" : [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description" : "`1` = *Pentateuch*, `2` = *Historical Books*, `3` = *Wisdom Books*, `4` = *Prophets*, `5` = *Gospels*, `6` = *Acts of the Apostles*, `7` = *Letters of Saint Paul*, `8` = *Catholic Letters*, `9` = *Apocalypse*", "xml" : { "attribute" : true } }, "book" : { "type" : "string", "description" : "Name of the book of the Bible in the language of the Bible version being quoted from", "xml" : { "attribute" : true } }, "bookabbrev" : { "type" : "string", "description" : "Abbreviated form of the book of the Bible in the language of the Bible version being quoted from", "xml" : { "attribute" : true } }, "booknum" : { "type" : "integer", "description" : "0 based index of the Book of the Bible in the Bible version being quoted from (not all versions have the same books in the same order, especially when considering differences between Catholic and evangelical versions). The value is returned as a number value ready to be used against index information for the Bible version being quoted from. The corresponding name of the Book of the Bible as used in the printed edition of the current Bible version can be retrieved using the `metadata.php` API endpoint, as can index information about the number of chapters in the book and the number of verses in each chapter.", "xml" : { "attribute" : true } }, "univbooknum" : { "type" : "string", "description" : "A number identifying the Book of the Bible according to the universally recognized Catholic version of the Canon of the Sacred Scriptures (*i.e. universally recognized by the Roman Catholic Church*). This is not a 0 based index, but rather `1` = *Genesis*, `2` = *Exodus*, etc. Therefore it is returned as a string, but can be treated as a number.", "enum" : [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "50", "51", "52", "53", "54", "55", "56", "57", "58", "59", "60", "61", "62", "63", "64", "65", "66", "67", "68", "69", "70", "71", "72", "73" ], "xml" : { "attribute" : true } }, "chapter" : { "type" : "integer", "description" : "Chapter of the book of the Bible in the Bible version that the verse is being quoted from", "xml" : { "attribute" : true } }, "versedescr" : { "type" : "string", "description" : "Not currently used, comes back as a `null` value. Could possible be used in the future for scholarly notes associated with a Bible verse", "nullable" : true, "xml" : { "attribute" : true } }, "verse" : { "type" : "string", "description" : "Verse Number of the verse being quoted. *N.B. this is returned as a string because it will not always necessarily be a number value, there are verses that have letters in them. The value must be treated as a string and not as a number.*", "xml" : { "attribute" : true } }, "verseequiv" : { "type" : "integer", "description" : "I'm not actually sure if this is currently being used or not, I believe the idea was to have a number value for those verses that have a letter in the verse number... Will mostly return a `null` value.", "nullable" : true, "xml" : { "attribute" : true } }, "text" : { "type" : "string", "description" : "Contains the actual text of the verse being quoted. May contain `newline` characters that may need to be dealt with. The **NABRE** version will contain ***it's own formatting tags that need to be dealt with***, whether that means producing the proper formatting associated with these tags, or removing them to have a basic formatting. The legal requirements for usage of the NABRE version require the proper formatting to be used where possible. Please [contact the project author](mailto:admin@bibleget.io) for information on how to deal with these tags and their formatting.", "xml" : { "attribute" : true } }, "version" : { "type" : "string", "description" : "the acronym of the Bible version being quoted from. For data associated with any given Bible version, for example index information, the `metadata.php` API endpoint can be used", "xml" : { "attribute" : true } }, "title1" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any first-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "title2" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any second-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "title3" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any third-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "originalquery" : { "type" : "string", "description" : "The original query (Bible reference indicated in the `query` parameter of the sent request) that the endpoint received, which produced this result.", "xml" : { "attribute" : true } } } }, "xml" : { "wrapped" : true, "name" : "results" } }, "errors" : { "type" : "array", "description" : "An array of any error messages that may have been generated indicating a badly formed `query` parameter, a bad value for the `version` parameter, or an API server error", "items" : { "type" : "string" } }, "info" : { "type" : "object", "description" : "An object containing metadata about the API endpoint", "properties" : { "ENDPOINT_VERSION" : { "type" : "string" } } } } }, "BibleQuoteXML" : { "type" : "object", "properties" : { "results" : { "type" : "array", "description" : "Array of objects each of which represents a Bible verse with all associated information", "items" : { "$ref" : "#/components/schemas/BibleQuoteResult" }, "xml" : { "name" : "results", "wrapped" : true } }, "errors" : { "type" : "array", "description" : "An array of any error messages that may have been generated indicating a badly formed `query` parameter, a bad value for the `version` parameter, or an API server error", "items" : { "type" : "string" } }, "info" : { "type" : "object", "description" : "An object containing metadata about the API endpoint", "properties" : { "ENDPOINT_VERSION" : { "type" : "string" } } } }, "xml" : { "name" : "BibleQuote" } }, "BibleQuoteResult" : { "type" : "object", "properties" : { "testament" : { "type" : "integer", "enum" : [ 1, 2 ], "description" : "`1` = *Old Testament*, `2` = *New Testament*", "xml" : { "attribute" : true } }, "section" : { "type" : "integer", "enum" : [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description" : "`1` = *Pentateuch*, `2` = *Historical Books*, `3` = *Wisdom Books*, `4` = *Prophets*, `5` = *Gospels*, `6` = *Acts of the Apostles*, `7` = *Letters of Saint Paul*, `8` = *Catholic Letters*, `9` = *Apocalypse*", "xml" : { "attribute" : true } }, "book" : { "type" : "string", "description" : "Name of the book of the Bible in the language of the Bible version being quoted from", "xml" : { "attribute" : true } }, "bookabbrev" : { "type" : "string", "description" : "Abbreviated form of the book of the Bible in the language of the Bible version being quoted from", "xml" : { "attribute" : true } }, "booknum" : { "type" : "integer", "description" : "0 based index of the Book of the Bible in the Bible version being quoted from (not all versions have the same books in the same order, especially when considering differences between Catholic and evangelical versions). The value is returned as a number value ready to be used against index information for the Bible version being quoted from. The corresponding name of the Book of the Bible as used in the printed edition of the current Bible version can be retrieved using the `metadata.php` API endpoint, as can index information about the number of chapters in the book and the number of verses in each chapter.", "xml" : { "attribute" : true } }, "univbooknum" : { "type" : "string", "description" : "A number identifying the Book of the Bible according to the universally recognized Catholic version of the Canon of the Sacred Scriptures (*i.e. universally recognized by the Roman Catholic Church*). This is not a 0 based index, but rather `1` = *Genesis*, `2` = *Exodus*, etc. Therefore it is returned as a string, but can be treated as a number.", "enum" : [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "50", "51", "52", "53", "54", "55", "56", "57", "58", "59", "60", "61", "62", "63", "64", "65", "66", "67", "68", "69", "70", "71", "72", "73" ], "xml" : { "attribute" : true } }, "chapter" : { "type" : "integer", "description" : "Chapter of the book of the Bible in the Bible version that the verse is being quoted from", "xml" : { "attribute" : true } }, "versedescr" : { "type" : "string", "description" : "Not currently used, comes back as a `null` value. Could possible be used in the future for scholarly notes associated with a Bible verse", "nullable" : true, "xml" : { "attribute" : true } }, "verse" : { "type" : "string", "description" : "Verse Number of the verse being quoted. *N.B. this is returned as a string because it will not always necessarily be a number value, there are verses that have letters in them. The value must be treated as a string and not as a number.*", "xml" : { "attribute" : true } }, "verseequiv" : { "type" : "integer", "description" : "I'm not actually sure if this is currently being used or not, I believe the idea was to have a number value for those verses that have a letter in the verse number... Will mostly return a `null` value.", "nullable" : true, "xml" : { "attribute" : true } }, "text" : { "type" : "string", "description" : "Contains the actual text of the verse being quoted. May contain `newline` characters that may need to be dealt with. The **NABRE** version will contain ***it's own formatting tags that need to be dealt with***, whether that means producing the proper formatting associated with these tags, or removing them to have a basic formatting. The legal requirements for usage of the NABRE version require the proper formatting to be used where possible. Please [contact the project author](mailto:admin@bibleget.io) for information on how to deal with these tags and their formatting.", "xml" : { "attribute" : true } }, "version" : { "type" : "string", "description" : "the acronym of the Bible version being quoted from. For data associated with any given Bible version, for example index information, the `metadata.php` API endpoint can be used", "xml" : { "attribute" : true } }, "title1" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any first-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "title2" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any second-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "title3" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any third-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "originalquery" : { "type" : "string", "description" : "The original query (Bible reference indicated in the `query` parameter of the sent request) that the endpoint received, which produced this result.", "xml" : { "attribute" : true } } }, "xml" : { "name" : "result" } }, "MetadataBibleVersions" : { "type" : "object", "properties" : { "validversions" : { "type" : "array", "description" : "An array of the acronyms of the Bible versions that are currently supported by the main BibleGet API endpoint", "items" : { "type" : "string" } }, "validversions_fullname" : { "type" : "object", "description" : "An object the keys of which are the acronyms of the Bible versions that are currently supported by the main BibleGet API endpoint, and the values of which are a pipe separated list of 1. The full name of the Bible version 2. The year it was published 3. The two letter ISO 639-1 code of the **language** of the Bible version", "additionalProperties" : { "type" : "string" } }, "copyrightversions" : { "type" : "array", "description" : "An array containing the acronyms of Bible versions that have a copyright holder, the usage of which is regulated under a legally binding agreement with the copyright holder. For example, some copyright holders (usually Episcopal Conferences for Catholic versions) may request that no more than a certain number of verses be issued from a single request to the endpoint (in other words, please don't try to copy the whole Bible through the BibleGet endpoint!). Enforcement of the usage required by the copyright holder is done by the endpoint itself, so applications cannot overcome these limits. If the owner of the endpoint notices that an application attempts in a sly manner to overcome these limitations, access to the main API endpoint may be denied to the application and authorization mechanisms will be necessarily put in place for usage of the endpoints. We are assuming a model of responsible usage for the time being, but if it becomes necessary access will be restricted and authorization will be required", "items" : { "type" : "string" } }, "errors" : { "type" : "array", "description" : "An array of any error messages that may have been generated indicating a badly formed `query` parameter or an API server error", "items" : { "type" : "string" } }, "info" : { "type" : "object", "description" : "An object containing metadata about the API endpoint", "properties" : { "ENDPOINT_VERSION" : { "type" : "string" } } } }, "xml" : { "name" : "BibleGetMetadata" } }, "MetadataBibleBooks" : { "type" : "object", "properties" : { "languages" : { "type" : "array", "description" : "An array indicating the languages supported by the main BibleGet endpoint, for the names of the Books of the Bible. The single languages are returned in the English form, all caps. The implict numbered index of this array will be useful for the data associated with the `results` key.", "items" : { "type" : "string" } }, "results" : { "type" : "array", "description" : "An array containing information about the names of the Bible books that can be used to make queries to the main endpoint. The implict numbered index of this array corresponds with the Bible books universally recognized by the Roman Catholic Church. Bible versions used by evangelicals will generally have a few less Bible books, so the index of reference is the Canon of the Scriptures as recognized by the Roman Catholic Church.", "items" : { "$ref" : "#/components/schemas/MetadataBibleBooksResult" } }, "errors" : { "type" : "array", "description" : "An array of any error messages that may have been generated indicating a badly formed `query` parameter or an API server error", "items" : { "type" : "string" } }, "info" : { "type" : "object", "description" : "An object containing metadata about the API endpoint", "properties" : { "ENDPOINT_VERSION" : { "type" : "string" } } } }, "xml" : { "name" : "BibleGetMetadata" } }, "MetadataVersionIndex" : { "type" : "object", "properties" : { "indexes" : { "type" : "object", "description" : "An object the *keys* of which are the *acronyms of the Bible versions as requested with the `versions` parameter*, and the corresponding *values* of which are objects with the index information associated with that Bible version.", "additionalProperties" : { "$ref" : "#/components/schemas/MetadataVersionIndexForVersion" } }, "errors" : { "type" : "array", "description" : "An array of any error messages that may have been generated indicating a badly formed `query` parameter, a bad value for the `version` parameter, or an API server error", "items" : { "type" : "string" } }, "info" : { "type" : "object", "description" : "An object containing metadata about the API endpoint", "properties" : { "ENDPOINT_VERSION" : { "type" : "string" } } } }, "xml" : { "name" : "BibleGetMetadata" } }, "MetadataBibleBooksResult" : { "type" : "array", "description" : "Each element of the `results` array will is an array whose implicit numbered index corresponds with the *LANGUAGES* supported by the main endoint, as can be found in the `languages` key of the returned data.", "items" : { "$ref" : "#/components/schemas/MetadataBibleBooksResultForLang" } }, "MetadataBibleBooksResultForLang" : { "type" : "array", "description" : "An array with a variable number of elements. The first two elements will always be present: 1. a pipe separated list of the possible Full names of the Bible book in the given language (if there are multiple possible forms that is; the pipe will be not be present if there is not a list of values) 2. a pipe separated list of the possible abbreviated forms of the Bible book in the given language (if there are multiple possible forms that is; the pipe will be not be present if there is not a list of values) 3. Any other elements will not be pipe separated lists but single strings of the possible alternate forms whether full or abbreviated ??? [note to myself: double check this, what was the reasoning behind this kind of structuring of the data?]", "items" : { "type" : "string" } }, "MetadataVersionIndexForVersion" : { "type" : "object", "description" : "", "properties" : { "abbreviations" : { "type" : "array", "description" : "An array containing the abbreviations of the books of the Bible as found in the published edition of this version of the Bible. These may not necessarily always be used as is for making requests to the main API endpoint because there is some possibility that they may conflict with other abbreviations used by other versions of the Bible in other languages for a different book of the Bible. These are only useful for displaying the exact abbreviations for that version of the Bible. For verification of the validity of a request made to the main API endpoint, the abbreviations produced from the request `query=biblebooks` should be used.", "items" : { "type" : "string" } }, "biblebooks" : { "type" : "array", "description" : "An array containing the full names of the books of the Bible as found in the published edition of this version of the Bible. The implicit numbered index of this array will not necessarily correspond with that of the Canon of the Scriptures as recognized by the Roman Catholic Church and as produced from the request `query=biblebooks`, because some evangelical versions for example may not have all of the books of the Bible as per the Canon recognized by the Roman Catholic Church.", "items" : { "type" : "string" } }, "chapter_limit" : { "type" : "array", "description" : "An array of number values which indicate the last possible chapter for each of the books listed in the above mentioned `biblebooks` array (or in the above mentioned `abbreviations` array). Again, the implicit numerical index of these values will not necessarily correspond with that of the Canon of Scriptures as recognized by the Roman Catholic Church, if the version of the Bible being quoted from does not have all of the books recognized by this same Canon. Each of these values is the actual last chapter of each of the books of the Bible in this version of the Bible, so it is not a zero based index number but it is the actual number of the last chapter of the book", "items" : { "type" : "integer" } }, "verse_limit" : { "type" : "array", "description" : "An array in which the implicit numerical index corresponds with the books listed in the above mentioned `biblebooks` array (or in the above mentioned `abbreviations` array). Each value of the array is another array which again contains numerical values; the total number of values found in each nested array corresponds with the number of chapters for each of these same books. So if the book of Genesis has 50 chapters (as we found out from the `chapter_limit` key), there will be 50 values in the first nested array within the `verse_limit` array. Each one of these 50 values indicates the verse limit (as in the last possible verse) for each of the 50 chapters in the book of Genesis. The same goes for each of the nested arrays contained herein. Again, the numbers in the nested arrays indicate the actual number of the last verse, it is not a zero based index.", "items" : { "type" : "array", "description" : "An array of numerical values indicating the last possible verse in the corresponding chapter of the corresponding book of the Bible in the given Bible version. The total number of values in this array corresponds with the number of chapters in the corresponding book of the Bible. If we are dealing with the book of Genesis which has 50 chapters (as we found out from the `chapter_limit` key), there will be 50 values in this array. Each one of these 50 values indicates the verse limit (as in the last possible verse) for each of the 50 chapters in the book of Genesis. Again, the numbers in this array indicate the actual number of the last verse, it is not a zero based index.", "items" : { "type" : "integer" } } }, "book_num" : { "type" : "array", "description" : "", "items" : { "type" : "array", "description" : "An array containing the number of each book as it would be in the Canon of the Scriptures as recognized by the Roman Catholic Church. These numbers are not based on a zero based index. `1` = *Genesis*, `2` = *Exodus*, etc. This can be very helpful in trying to glue all of the metadata information together, between valid book names that can be used with their Roman Catholic Canon based index, and actual book names in a single version of the Bible where the number of elements might not be the same as those in the Roman Catholic Canon.", "items" : { "type" : "integer" } } } } }, "KeywordSearchJSON" : { "type" : "object", "properties" : { "results" : { "type" : "array", "description" : "Array of objects each of which represents a Bible verse with all associated information", "items" : { "type" : "object", "properties" : { "testament" : { "type" : "integer", "enum" : [ 1, 2 ], "description" : "`1` = *Old Testament*, `2` = *New Testament*", "xml" : { "attribute" : true } }, "section" : { "type" : "integer", "enum" : [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description" : "`1` = *Pentateuch*, `2` = *Historical Books*, `3` = *Wisdom Books*, `4` = *Prophets*, `5` = *Gospels*, `6` = *Acts of the Apostles*, `7` = *Letters of Saint Paul*, `8` = *Catholic Letters*, `9` = *Apocalypse*", "xml" : { "attribute" : true } }, "book" : { "type" : "string", "description" : "Name of the book of the Bible in the language of the Bible version being quoted from", "xml" : { "attribute" : true } }, "bookabbrev" : { "type" : "string", "description" : "Abbreviated form of the book of the Bible in the language of the Bible version being quoted from", "xml" : { "attribute" : true } }, "booknum" : { "type" : "integer", "description" : "0 based index of the Book of the Bible in the Bible version being quoted from (not all versions have the same books in the same order, especially when considering differences between Catholic and evangelical versions). The value is returned as a number value ready to be used against index information for the Bible version being quoted from. The corresponding name of the Book of the Bible as used in the printed edition of the current Bible version can be retrieved using the `metadata.php` API endpoint, as can index information about the number of chapters in the book and the number of verses in each chapter.", "xml" : { "attribute" : true } }, "univbooknum" : { "type" : "string", "description" : "A number identifying the Book of the Bible according to the universally recognized Catholic version of the Canon of the Sacred Scriptures (*i.e. universally recognized by the Roman Catholic Church*). This is not a 0 based index, but rather `1` = *Genesis*, `2` = *Exodus*, etc. Therefore it is returned as a string, but can be treated as a number.", "enum" : [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "50", "51", "52", "53", "54", "55", "56", "57", "58", "59", "60", "61", "62", "63", "64", "65", "66", "67", "68", "69", "70", "71", "72", "73" ], "xml" : { "attribute" : true } }, "chapter" : { "type" : "integer", "description" : "Chapter of the book of the Bible in the Bible version that the verse is being quoted from", "xml" : { "attribute" : true } }, "versedescr" : { "type" : "string", "description" : "Not currently used, comes back as a `null` value. Could possible be used in the future for scholarly notes associated with a Bible verse", "nullable" : true, "xml" : { "attribute" : true } }, "verse" : { "type" : "string", "description" : "Verse Number of the verse being quoted. *N.B. this is returned as a string because it will not always necessarily be a number value, there are verses that have letters in them. The value must be treated as a string and not as a number.*", "xml" : { "attribute" : true } }, "verseequiv" : { "type" : "integer", "description" : "I'm not actually sure if this is currently being used or not, I believe the idea was to have a number value for those verses that have a letter in the verse number... Will mostly return a `null` value.", "nullable" : true, "xml" : { "attribute" : true } }, "text" : { "type" : "string", "description" : "Contains the actual text of the verse being quoted. May contain `newline` characters that may need to be dealt with. The **NABRE** version will contain ***it's own formatting tags that need to be dealt with***, whether that means producing the proper formatting associated with these tags, or removing them to have a basic formatting. The legal requirements for usage of the NABRE version require the proper formatting to be used where possible. Please [contact the project author](mailto:admin@bibleget.io) for information on how to deal with these tags and their formatting.", "xml" : { "attribute" : true } }, "version" : { "type" : "string", "description" : "the acronym of the Bible version being quoted from. For data associated with any given Bible version, for example index information, the `metadata.php` API endpoint can be used", "xml" : { "attribute" : true } }, "title1" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any first-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "title2" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any second-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "title3" : { "type" : "string", "description" : "not currently used. The original idea (which may yet be implemented) was for this to contain any third-level title text preceding the given verse in the version of the Bible being quoted from.", "xml" : { "attribute" : true } }, "originalquery" : { "type" : "string", "description" : "The reference to the single verse in this result (*{Book}{Chapter}*:*{Verse}*).", "xml" : { "attribute" : true } } } }, "xml" : { "wrapped" : true, "name" : "results" } }, "errors" : { "type" : "array", "description" : "An array of any error messages that may have been generated indicating a badly formed `query` parameter, a bad value for the `version` parameter, or an API server error", "items" : { "type" : "string" } }, "info" : { "type" : "object", "description" : "An object containing metadata about the API endpoint", "properties" : { "ENDPOINT_VERSION" : { "type" : "string", "description" : "The current version of the API endpoint. This may be useful information because the data produced by the endpoint may change over time, it is useful to know which data is associated with which version of the endpoint. For example, if an application caches data returned by the endpoint, but there has been a change to the structure of the data in a new version of the API, the application would know how to deal with emptying the cache and requesting new data from the updated endpoint." }, "keyword" : { "type" : "string", "description" : "The Bible version in which the search by keyword was performed, as indicated in the `version` parameter in the request" }, "version" : { "type" : "string", "description" : "The keyword used to perform the search as indicated by the `keyword` parameter in the request" } } } } }, "KeywordSearchXML" : { "type" : "object", "properties" : { "results" : { "type" : "array", "description" : "Array of objects each of which represents a Bible verse in which the searched keyword was found, with all associated information", "items" : { "$ref" : "#/components/schemas/BibleQuoteResult" }, "xml" : { "name" : "results", "wrapped" : true } }, "errors" : { "type" : "array", "description" : "An array of any error messages that may have been generated indicating a badly formed `query` parameter, a bad value for the `version` parameter, or an API server error", "items" : { "type" : "string" } }, "info" : { "type" : "object", "description" : "An object containing metadata about the API endpoint", "properties" : { "ENDPOINT_VERSION" : { "type" : "string", "description" : "The current version of the API endpoint. This may be useful information because the data produced by the endpoint may change over time, it is useful to know which data is associated with which version of the endpoint. For example, if an application caches data returned by the endpoint, but there has been a change to the structure of the data in a new version of the API, the application would know how to deal with emptying the cache and requesting new data from the updated endpoint." }, "keyword" : { "type" : "string", "description" : "The Bible version in which the search by keyword was performed, as indicated in the `version` parameter in the request" }, "version" : { "type" : "string", "description" : "The keyword used to perform the search as indicated by the `keyword` parameter in the request" } } } }, "xml" : { "name" : "BibleQuote" } } }, "parameters" : { "query" : { "name" : "query", "in" : "query", "description" : "Bible reference using standard Bible citation notation. ", "required" : true, "schema" : { "type" : "string" }, "examples" : { "internationalNotation" : { "value" : "Genesis1,1-5.7-9", "summary" : "International style Bible citation notation" }, "englishNotation" : { "value" : "Genesis1:1-5,7-9", "summary" : "English style Bible citation notation" }, "chainedQueries" : { "value" : "John3:16;1John4:7-8", "summary" : "Chaining together multiple Bible quotes using a semicolon" }, "chainedQueriesSameBook" : { "value" : "Matthew1:1-5;2:6-8", "summary" : "Chaining together multiple Bible quotes from the same book using a semicolon" } } }, "version" : { "name" : "version", "in" : "query", "description" : "Bible version or versions from which to retrieve the Bible quote. A list of valid versions can be retrieved from the `metadata.php` API using `query=bibleversions`", "required" : true, "schema" : { "type" : "array", "items" : { "type" : "string" } }, "style" : "form", "explode" : false, "examples" : { "multipleVersions" : { "value" : [ "NABRE", "CEI2008" ], "summary" : "retrieve Bible quote from multiple Bible versions" }, "singleVersion" : { "value" : [ "NVBSE" ], "summary" : "retrieve Bible quote from a single Bible version" } } }, "return" : { "name" : "return", "in" : "query", "description" : "Type of data that should be returned in the response", "required" : false, "schema" : { "type" : "string", "enum" : [ "json", "xml", "html" ], "default" : "json" }, "examples" : { "json" : { "value" : "json", "summary" : "return data in JSON format" }, "xml" : { "value" : "xml", "summary" : "return data in XML format" }, "html" : { "value" : "html", "summary" : "return data in HTML format" } } }, "appid" : { "name" : "appid", "in" : "query", "description" : "Unique identifier of the application making the request, to be agreed upon with the owner of the API endpoint", "required" : true, "schema" : { "type" : "string" }, "example" : "swaggerhub" }, "pluginversion" : { "name" : "pluginversion", "in" : "query", "description" : "Version number of the application making the request. Useful not only for statistics, to help understand which version of an application is being actively used, but also (especially in the case of the official applications) to help deal with possibly breaking changes between the application version and versions of the API endpoint", "required" : false, "schema" : { "type" : "string" }, "example" : "v1.0" }, "domain" : { "name" : "domain", "in" : "query", "description" : "In the case of web based applications, should indicate the domain from which the request is generated. Currently used by the official plugin for WordPress to better understand usage of the plugin and monitor requests. When the application or plugin making the request can be installed on different domains (as is the case with the WordPress plugin), this value should be generated dynamically from a server variable identifying the domain. If instead it will always be the same domain making the requests, the value can be hardcoded with the actual domain.", "required" : false, "schema" : { "type" : "string" }, "example" : "app.swaggerhub.com" } } } }