### Install the Free Use Bible API Client Source: https://github.com/helloaolab/bible-api/blob/main/packages/free-use-bible-api/README.md Install the package using npm, pnpm, or yarn. ```bash npm install free-use-bible-api ``` ```bash pnpm add free-use-bible-api ``` ```bash yarn add free-use-bible-api ``` -------------------------------- ### Install Free Use Bible API Tools Source: https://github.com/helloaolab/bible-api/blob/main/packages/free-use-bible-api-test/README.md Install the tools package using npm. ```bash $ npm install @helloao/tools ``` -------------------------------- ### Install Free Use Bible API Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/README.md Install the Free Use Bible API package using npm. ```bash npm install free-use-bible-api ``` -------------------------------- ### Example Available Commentaries JSON Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md An example of the JSON response structure for the '/api/available_commentaries.json' endpoint. This shows the expected fields for each commentary. ```json { "commentaries": [ { "id": "adam-clarke", "name": "Adam Clarke Bible Commentary", "website": "https://en.wikipedia.org/wiki/Adam_Clarke", "licenseUrl": "https://creativecommons.org/publicdomain/mark/1.0/", "englishName": "Adam Clarke Bible Commentary", "language": "eng", "textDirection": "rtl", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/c/adam-clarke/books.json", "numberOfBooks": 57, "totalNumberOfChapters": 854, "totalNumberOfVerses": 13318, "languageName": "English", "languageEnglishName": "English" } ] } ``` -------------------------------- ### Example API Response JSON Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md An example of the JSON response when fetching a commentary profile. This illustrates the data structure for commentary details, profile information, and the content itself. ```json { "commentary": { "id": "tyndale", "name": "Tyndale Open Study Notes", "website": "https://tyndaleopenresources.com/", "licenseUrl": "https://creativecommons.org/licenses/by-sa/4.0/", "licenseNotes": "Changes were made to the content to change the format to JSON to make it compatible with the Free Use Bible API. No changes were made to the content contained in the XML formatting.", "englishName": "Tyndale Open Study Notes", "language": "eng", "textDirection": "rtl", "sha256": "62fa003ca326f8ab22a04accb2a49d2b5865ce2cecd74284228e1be08edd5e10", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/c/tyndale/books.json", "listOfProfilesApiLink": "/api/c/tyndale/profiles.json", "numberOfBooks": 69, "totalNumberOfChapters": 1243, "totalNumberOfVerses": 15757, "totalNumberOfProfiles": 125, "languageName": "English", "languageEnglishName": "English" }, "profile": { "id": "aaron", "reference": { "book": "EXO", "chapter": 4, "verse": 14, "endVerse": 16 }, "subject": "Aaron", "thisProfileLink": "/api/c/tyndale/profiles/aaron.json", "referenceChapterLink": "/api/c/tyndale/EXO/4.json" }, "content": [ "Aaron\n\nMoses’ older brother, Aaron (see Exod 6:20; 7:7), played a crucial role in founding Israel and its institutions, particularly the priesthood. He first appears after Moses’ calling at the burning bush (Exod 3:1–4:17). Moses was reluctant to accept his divine commission, claiming that he was unfit to lead the Israelites out of Egypt because his words tended to “get tangled” (Exod 4:10). Despite God’s assurances, Moses continued to object until God appointed Aaron to be Moses’ mouthpiece. Thereafter, Aaron was often at Moses’ side, speaking to the Israelite leaders and demanding that Pharaoh let the Israelites leave Egypt (Exod 5:1-5).\n\nDuring the Israelites’ wilderness wanderings, God appointed Aaron and his sons to be set apart and dedicated as priests (Exod 28:1-5; 29:1-46; Lev 8:1-36). Thus, Aaron became Israel’s first high priest. Aaron’s role as high priest was especially prominent on the annual Day of Atonement, the only day when the high priest entered the Most Holy Place to purify it from the effects of Israel’s sins (Lev 16). Before the high priest could do so, however, he had to offer a sacrifice to atone for his own sins.\n\nAaron was an imperfect leader. While Moses was on Mount Sinai receiving the law from God, Aaron helped the people make an idol (Exod 32). When Moses returned, Aaron gave poor excuses and blamed the people. This event resulted in the death of three thousand Israelites, as well as a plague.\n\nAaron and his sister, Miriam, once wrongly challenged Moses’ authority, resulting in a temporary state of leprosy for Miriam (Num 12). Later, when other Levites challenged Aaron’s authority, God affirmed Aaron’s role by making his staff bud with almond blossoms (Num 17). However, because Moses and Aaron challenged God’s authority (Num 20:1-13), they both died in the wilderness without entering the Promised Land (Num 20:22-29).\n\nJesus has become the Great High Priest, far surpassing Aaron’s priestly authority and effectiveness (see Heb 7–10).\n\nPassages for Further Study\n\nExod 4:14-17, 27-31; 6:20-27; 7:1-2; 28:1-5; 32:1-25; Num 12:1-12; 20:1-13, 22-29; Acts 7:39-41" ] } ``` -------------------------------- ### Complete Translation JSON Example Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md Example JSON response for the /api/BSB/complete.json endpoint, showing translation metadata and book structure. ```json { "translation": { "id": "BSB", "name": "Berean Standard Bible", "website": "https://berean.bible/", "licenseUrl": "https://berean.bible/", "licenseNotes": null, "shortName": "BSB", "englishName": "Berean Standard Bible", "language": "eng", "textDirection": "ltr", "sha256": "b2898c49cadb50fd8763feb9e2f74a90a3817e33408a24b6cbf09e7a950dde97", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/BSB/books.json", "completeTranslationApiLink": "/api/BSB/complete.json", "numberOfBooks": 66, "totalNumberOfChapters": 1189, "totalNumberOfVerses": 31086, "languageName": "English", "languageEnglishName": "English" }, "books": [ { "id": "GEN", "name": "Genesis", "commonName": "Genesis", "title": "Genesis", "order": 1, "numberOfChapters": 50, "totalNumberOfVerses": 1533, "chapters": [ { "numberOfVerses": 31, "thisChapterAudioLinks": { "gilbert": "https://openbible.com/audio/gilbert/BSB_01_Gen_001_G.mp3", "hays": "https://openbible.com/audio/hays/BSB_01_Gen_001_H.mp3", "souer": "https://openbible.com/audio/souer/BSB_01_Gen_001.mp3" }, "chapter": { "number": 1, "content": [ { "type": "heading", "content": [ "The Creation" ] }, { "type": "verse", "number": 1, "content": [ "In the beginning God created the heavens and the earth." ] }, { "type": "line_break" }, { "type": "verse", "number": 2, "content": [ "Now the earth was formless and void, and darkness was over the surface of the deep. And the Spirit of God was hovering over the surface of the waters." ] }, ] } } ] } ] } ``` -------------------------------- ### Get First Chapter of a Bible Book Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/api-reference/FreeUseBibleApi.md Retrieves the first chapter of a specified book. This is useful for starting at the beginning of any translation, commentary, or dataset. Returns null if the book has no chapters. ```typescript const api = new FreeUseBibleApi(); const books = await api.getTranslationBooks('BSB'); const genesis = books.books[0]; // Genesis const firstChapter = await api.getFirstChapter(genesis); if (firstChapter) { console.log(`First chapter: ${firstChapter.chapter.number}`); console.log(`Verses: ${firstChapter.numberOfVerses}`); } ``` -------------------------------- ### API Response Example for /api/d/open-cross-ref/books.json Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md Example JSON response structure for the API endpoint that lists books in a dataset. This shows the detailed information provided for the dataset and each book within it. ```json { "dataset": { "id": "open-cross-ref", "name": "Bible Cross References", "website": "https://www.openbible.info/labs/cross-references/", "licenseUrl": "https://creativecommons.org/licenses/by/4.0/", "licenseNotes": "Changes were made to the data to fit the Free Use Bible API format.", "englishName": "Bible Cross References", "language": "eng", "textDirection": "ltr", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/d/open-cross-ref/books.json", "numberOfBooks": 66, "totalNumberOfChapters": 1189, "totalNumberOfVerses": 29364, "totalNumberOfReferences": 344799, "languageName": "English", "languageEnglishName": "English" }, "books": [ { "id": "GEN", "datasetId": "open-cross-ref", "order": 1, "numberOfChapters": 50, "firstChapterNumber": 1, "firstChapterApiLink": "/api/d/open-cross-ref/GEN/1.json", "lastChapterNumber": 50, "lastChapterApiLink": "/api/d/open-cross-ref/GEN/50.json", "totalNumberOfVerses": 1382, "totalNumberOfReferences": 13327 }, { "id": "EXO", "datasetId": "open-cross-ref", "order": 2, "numberOfChapters": 40, "firstChapterNumber": 1, "firstChapterApiLink": "/api/d/open-cross-ref/EXO/1.json", "lastChapterNumber": 40, "lastChapterApiLink": "/api/d/open-cross-ref/EXO/40.json", "totalNumberOfVerses": 1084, "totalNumberOfReferences": 9974 }, ] } ``` -------------------------------- ### API Response Example Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md This JSON object shows an example of the response structure when requesting the list of books for the 'adam-clarke' commentary. It includes commentary details and a list of books. ```json { "commentary": { "id": "adam-clarke", "name": "Adam Clarke Bible Commentary", "website": "https://en.wikipedia.org/wiki/Adam_Clarke", "licenseUrl": "https://creativecommons.org/publicdomain/mark/1.0/", "englishName": "Adam Clarke Bible Commentary", "language": "eng", "textDirection": "rtl", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/c/adam-clarke/books.json", "numberOfBooks": 57, "totalNumberOfChapters": 854, "totalNumberOfVerses": 13318, "languageName": "English", "languageEnglishName": "English" }, "books": [ { "id": "GEN", "commentaryId": "adam-clarke", "name": "Genesis", "commonName": "Genesis", "introduction": "Preface to the Book of Genesis, Every believer in Divine revelation finds himself amply justified in taking for granted that the Pentateuch is the work of Moses. For more than 3000 years this has been the invariable opinion of those who were best qualified to form a correct judgment on this subject. The Jewish Church, from its most remote antiquity, has ascribed the work to no other hand; and the Christian Church, from its foundation, has attributed it to the Jewish lawgiver alone. The most respectable heathens have concurred in this testimony, and Jesus Christ and his apostles have completed the evidence, and have put the question beyond the possibility of being doubted by those who profess to believe the Divine authenticity of the New Testament. As to those who, in opposition to all these proofs, obstinately persist in their unbelief, they are worthy of little regard, as argument is lost on their unprincipled prejudices, and demonstration on their minds, because ever willfully closed against the light. When they have proved that Moses is not the author of this work, the advocates of Divine revelation will reconsider the grounds of their faith. That there are a few things in the Pentateuch which seem to have been added by a later hand there can be little doubt; among these some have reckoned, perhaps without reason, the following passage, Gen 12:6 : \"And the Canaanite was then in the land\"; but see the note on Gen 12:6. Num 21:14, \"In the book of the wars of the Lord,\" was probably a marginal note, which in time got into the text; see the note on Num 21:14." } ] } ``` -------------------------------- ### Error Handling Example Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/endpoints.md Details the error handling for 404 Not Found responses, specifying common causes and providing an example error response structure. ```APIDOC ## Error Handling 404 responses indicate: - Invalid translation/commentary/dataset ID - Invalid book ID - Invalid chapter number - Non-existent combination Example error response: ```bash HTTP/1.1 404 Not Found Content-Type: application/json { "error": "Not Found" } ``` ``` -------------------------------- ### Quick Start with Free Use Bible API Source: https://github.com/helloaolab/bible-api/blob/main/packages/free-use-bible-api/README.md Initialize the API client and fetch available translations, books, and chapter details. ```typescript import { FreeUseBibleApi } from 'free-use-bible-api'; const api = new FreeUseBibleApi(); const available = await api.getAvailableTranslations(); console.log('Total translations:', available.translations.length); const books = await api.getTranslationBooks('BSB'); console.log('Books in BSB:', books.books.length); const chapter = await api.getTranslationBookChapter('BSB', 'GEN', 1); console.log('Verses in Genesis 1:', chapter.numberOfVerses); ``` -------------------------------- ### Example JSON Response for Available Translations Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md This is an example of the JSON response structure when requesting available translations from the API. ```json { "translations": [ { "id": "BSB", "name": "Berean Standard Bible", "website": "https://berean.bible/", "licenseUrl": "https://berean.bible/", "shortName": "BSB", "englishName": "Berean Standard Bible", "language": "eng", "textDirection": "ltr", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/BSB/books.json", "numberOfBooks": 66, "totalNumberOfChapters": 1189, "totalNumberOfVerses": 31086, "languageName": "English", "languageEnglishName": "English" } ] } ``` -------------------------------- ### Example HTTP Requests using cURL Source: https://github.com/helloaolab/bible-api/blob/main/packages/free-use-bible-api/README.md Demonstrates how to make direct HTTP requests to the Bible API endpoints using cURL. ```bash curl https://bible.helloao.org/api/available_translations.json ``` ```bash curl https://bible.helloao.org/api/BSB/books.json ``` ```bash curl https://bible.helloao.org/api/BSB/GEN/1.json ``` ```bash curl https://bible.helloao.org/api/available_commentaries.json ``` ```bash curl https://bible.helloao.org/api/available_datasets.json ``` -------------------------------- ### getFirstChapter() Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/INDEX.md Gets the first chapter of the current book or translation. ```APIDOC ## getFirstChapter() ### Description Gets the first chapter of the current book or translation. ### Method SDK Method ### Parameters None explicitly documented for this method signature. ### Response - Returns information about the first chapter. ``` -------------------------------- ### Audio Links Example Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/endpoints.md Shows how chapter responses provide audio links for different language formats, enabling playback of chapter content. ```APIDOC ## Audio Links Chapter responses include audio links for different formats: ```typescript thisChapterAudioLinks: { "en-US": "https://audio.bible.helloao.org/audio/BSB/GEN/1.mp3", "en-GB": "https://audio.bible.helloao.org/audio/BSB-en-GB/GEN/1.mp3" } ``` ``` -------------------------------- ### getNextChapter() Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/INDEX.md Gets the next chapter based on the current chapter context. ```APIDOC ## getNextChapter() ### Description Gets the next chapter based on the current chapter context. ### Method SDK Method ### Parameters None explicitly documented for this method signature. ### Response - Returns information about the next chapter. ``` -------------------------------- ### Get a Chapter from a Dataset Source: https://github.com/helloaolab/bible-api/blob/main/docs/guide/making-requests.md Fetches a specific chapter's content from a given book and dataset. ```APIDOC ## GET /api/d/{dataset}/{book}/{chapter}.json ### Description Retrieves the content for a specific chapter from a given book and dataset. ### Method GET ### Endpoint /api/d/{dataset}/{book}/{chapter}.json ### Parameters #### Path Parameters - **dataset** (string) - Required - The identifier for the dataset (e.g., open-cross-ref). - **book** (string) - Required - The identifier for the book (e.g., GEN). - **chapter** (integer) - Required - The chapter number. ### Response #### Success Response (200) - **chapterContent** (object) - An object containing the content of the specified chapter from the dataset. ``` -------------------------------- ### Retrieve Genesis Chapter 1 Verses Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md Example of fetching verses from Genesis chapter 1, including content and footnotes. ```json { "book": "Genesis", "chapter": 1, "verses": [ { "type": "verse", "number": 1, "content": [ "In the beginning God created the heavens and the earth." ] }, { "type": "verse", "number": 2, "content": [ "Now the earth was formless and empty, darkness was over the surface of the deep, and the Spirit of God was hovering over the waters." ] }, { "type": "verse", "number": 3, "content": [ "And God said, \"Let there be light,\" and there was light." ] }, { "type": "verse", "number": 4, "content": [ "God saw that the light was good, and he separated the light from the darkness." ] }, { "type": "verse", "number": 5, "content": [ "God called the light \"day,\" and the darkness he called \"night.\", { "lineBreak": true }, "And there was evening, and there was morning—the first day.", { "noteId": 1 } ] } ], "footnotes": [ { "noteId": 0, "text": "Cited in 2 Corinthians 4:6", "caller": "+", "reference": { "chapter": 1, "verse": 3 } }, { "noteId": 1, "text": "Literally day one", "caller": "+", "reference": { "chapter": 1, "verse": 5 } }, { "noteId": 2, "text": "Or a canopy or a firmament or a vault; also in verses 7, 8, 14, 15, 17, and 20", "caller": "+", "reference": { "chapter": 1, "verse": 6 } }, { "noteId": 3, "text": "MT; Syriac and over all the beasts of the earth", "caller": "+", "reference": { "chapter": 1, "verse": 26 } }, { "noteId": 4, "text": "Cited in Matthew 19:4 and Mark 10:6", "caller": "+", "reference": { "chapter": 1, "verse": 27 } } ] } ``` -------------------------------- ### Get Available Commentaries Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/endpoints.md Use this endpoint to retrieve a list of all available Bible commentaries. No parameters are required. ```bash curl https://bible.helloao.org/api/available_commentaries.json ``` -------------------------------- ### Example Client Error Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/errors.md Illustrates the format of a JavaScript Error object thrown by the client for failed requests. ```typescript Error: Failed request to https://bible.helloao.org/api/invalid/books.json. Status: 404 Not Found ``` -------------------------------- ### Example Available Datasets JSON Response Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md This JSON structure represents the response from the `/api/available_datasets.json` endpoint, detailing a single available dataset. ```json { "datasets": [ { "id": "open-cross-ref", "name": "Bible Cross References", "website": "https://www.openbible.info/labs/cross-references/", "licenseUrl": "https://creativecommons.org/licenses/by/4.0/", "licenseNotes": "Changes were made to the data to fit the Free Use Bible API format.", "englishName": "Bible Cross References", "language": "eng", "textDirection": "ltr", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/d/open-cross-ref/books.json", "numberOfBooks": 66, "totalNumberOfChapters": 1189, "totalNumberOfVerses": 29364, "totalNumberOfReferences": 344799, "languageName": "English", "languageEnglishName": "English" } ] } ``` -------------------------------- ### Fetch a Chapter from a Dataset Source: https://github.com/helloaolab/bible-api/blob/main/docs/guide/making-requests.md Get the content of a specific chapter from a dataset. You must provide the dataset identifier, book, and chapter number. ```javascript const dataset = 'open-cross-ref'; const book = 'GEN'; const chapter = 1; // Get Genesis 1 from the open-cross-ref dataset fetch(`https://bible.helloao.org/api/d/${dataset}/${book}/${chapter}.json`) .then(request => request.json()) .then(chapter => { console.log('Genesis 1 (open-cross-ref):', chapter); }); ``` -------------------------------- ### Fetch Available Datasets Source: https://github.com/helloaolab/bible-api/blob/main/docs/guide/making-requests.md Get a list of all available datasets that can be queried from the API. This includes various collections of biblical data. ```javascript fetch(`https://bible.helloao.org/api/available_datasets.json`) .then(request => request.json()) .then(availableDatasets => { console.log('The API has the following datasets:', availableDatasets); }); ``` -------------------------------- ### Navigate Through Bible Chapters Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/README.md Iterates through Bible chapters sequentially, starting from a given chapter, and prints the book and chapter number. ```typescript let chapter = await api.getTranslationBookChapter('BSB', 'GEN', 1); while (chapter) { console.log(`${chapter.book.name} ${chapter.chapter.number}`); chapter = await api.getNextChapter(chapter); } ``` -------------------------------- ### HTTP Endpoints Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/COMPLETION_REPORT.txt The Free Use Bible API exposes 9 HTTP GET endpoints for retrieving Bible data. These endpoints cover translations, commentaries, and dataset information, each fully documented with request and response schemas, status codes, and examples. ```APIDOC ## HTTP Endpoints ### Description This section details the 9 available HTTP GET endpoints for interacting with the Free Use Bible API. Each endpoint is designed for specific data retrieval tasks, including accessing different Bible translations, commentaries, and dataset information. ### Endpoints #### Translation Endpoints (4) - **Method:** GET - **Endpoint:** (Details for specific translation endpoints not provided in source) - **Description:** Retrieve data related to various Bible translations. #### Commentary Endpoints (2) - **Method:** GET - **Endpoint:** (Details for specific commentary endpoints not provided in source) - **Description:** Access commentary texts for biblical passages. #### Dataset Endpoints (2) - **Method:** GET - **Endpoint:** (Details for specific dataset endpoints not provided in source) - **Description:** Retrieve information about available datasets. ### Parameters #### Path Parameters - (Details for path parameters not provided in source) #### Query Parameters - (Details for query parameters not provided in source) ### Request Body - (Not applicable for these GET endpoints) ### Response #### Success Response (200) - **Schema:** (Details for response schemas not provided in source) - **Description:** Returns the requested Bible data in a structured format. #### Error Response (404) - **Description:** Returned when the requested resource or endpoint is not found. ### Request Example - (curl examples provided in source, but not detailed here) ### Response Example - (Response schemas and examples provided in source, but not detailed here) ``` -------------------------------- ### Hello AO CLI Usage Help Source: https://github.com/helloaolab/bible-api/blob/main/packages/helloao-cli/README.md Displays the main usage instructions and available commands for the Hello AO CLI. ```bash Usage: helloao [options] [command] A CLI for managing a Free Use Bible API. Options: -V, --version output the version number -h, --help display help for command Commands: init [options] [path] Initialize a new Bible API DB. generate-translation-metadata Generates a metadata file for a translation. import-translation [options] [dirs...] Imports a translation from the given directory into the database. import-translations [options] Imports all translations from the given directory into the database. import-commentary [options] [dirs...] Imports a commentary from the given directory into the database. import-commentaries [options] Imports all commentaries from the given directory into the database. upload-test-translation [options] Uploads a translation to the HelloAO Free Bible API test S3 bucket. Requires access to the HelloAO Free Bible API test S3 bucket. For inquiries, please contact hello@helloao.org. upload-test-translations [options] Uploads all the translations in the given input directory to the HelloAO Free Bible API test S3 bucket. Requires access to the HelloAO Free Bible API test S3 bucket. For inquiries, please contact hello@helloao.org. generate-translation-files [options] Generates API files from the given input translation. generate-translations-files [options] Generates API files from the given input translations. upload-api-files [options] Uploads API files to the specified destination. For S3, use the format s3://bucket-name/path/to/folder. source-translations [options] [translations...] Finds translation sources from ebible.org and downloads it. list-ebible-translations [search] List available eBible translations. Optionally filter by search term. fetch-audio [options] [translations...] Fetches the specified audio translations and places them in the given directory. Translations should be in the format "translationId/audioId". e.g. "BSB/gilbert" fetch-bible-metadata Fetches the Theographic bible metadata and places it in the given directory. fetch-tyndale-open-resources Fetches the Tyndale Open Bible Resources and places it in the given directory. help [command] display help for command ``` -------------------------------- ### Development Setup with Custom Server Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/configuration.md Configures the FreeUseBibleApi client for development, allowing it to connect to a local server if not in a production environment. It dynamically sets the endpoint based on the NODE_ENV variable. ```typescript const isProduction = process.env.NODE_ENV === 'production'; const api = new FreeUseBibleApi({ endpoint: isProduction ? 'https://bible.helloao.org/' : 'http://localhost:3000/' }); ``` -------------------------------- ### Initialize FreeUseBibleApi with Defaults Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/configuration.md Instantiates the FreeUseBibleApi client using default configuration values. No specific options are provided. ```typescript import { FreeUseBibleApi } from 'free-use-bible-api'; // Use defaults const api = new FreeUseBibleApi(); ``` -------------------------------- ### Production Setup for FreeUseBibleApi Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/configuration.md Configures the FreeUseBibleApi client for a production environment, using environment variables for the endpoint and cache settings. Defaults to the public API if environment variables are not set. ```typescript const api = new FreeUseBibleApi({ endpoint: process.env.BIBLE_API_URL || 'https://bible.helloao.org/', useCache: !process.env.DISABLE_CACHE }); ``` -------------------------------- ### Instantiate FreeUseBibleApi Client Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/api-reference/FreeUseBibleApi.md Create a new instance of the FreeUseBibleApi client. You can optionally provide configuration options such as the API endpoint and cache settings. ```typescript import { FreeUseBibleApi } from 'free-use-bible-api'; const api = new FreeUseBibleApi(); const apiWithOptions = new FreeUseBibleApi({ endpoint: 'https://bible.helloao.org/', useCache: true }); ``` -------------------------------- ### Basic Usage of FreeUseBibleApi Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/README.md Demonstrates basic usage of the FreeUseBibleApi client, including fetching available translations, retrieving a chapter, and formatting chapter text. Ensure the 'free-use-bible-api' package is installed. ```typescript import { FreeUseBibleApi } from 'free-use-bible-api'; const api = new FreeUseBibleApi(); // Get available translations const available = await api.getAvailableTranslations(); console.log('Translations:', available.translations.length); // Get a chapter const chapter = await api.getTranslationBookChapter('BSB', 'GEN', 1); console.log(`${chapter.book.name} ${chapter.chapter.number}`); // Format and display const text = api.getChapterVerseText(chapter); console.log(text); ``` -------------------------------- ### Get Bible Translation Books Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/api-reference/FreeUseBibleApi.md Retrieves a list of books for a specified Bible translation. Use this to get available books within a translation like 'BSB' or 'eng_kjv'. ```typescript const api = new FreeUseBibleApi(); const books = await api.getTranslationBooks('BSB'); console.log('Translation:', books.translation.name); console.log('Number of books:', books.books.length); console.log('First book:', books.books[0].name); // Genesis ``` -------------------------------- ### Get a SQL Database Source: https://github.com/helloaolab/bible-api/blob/main/packages/helloao-cli/README.md Establishes a connection to a SQL database file. Ensure the database file exists or will be created at the specified path. Remember to close the database connection when finished. ```typescript import { db } from '@helloao/cli'; const pathToDb = './bible-database.db'; const database = await db.getDb(pathToDb); // do work on the database // Close it when you are done. database.close(); ``` -------------------------------- ### Example: Formatting a Verse Range Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/api-reference/utility-methods.md Shows how to format a range of verses within the same chapter using `formatReference`. Assumes a book object is already available. ```typescript const rangeRef = api.formatReference(genesis, { chapter: 1, verse: 1, endVerse: 5 }); console.log(rangeRef); // "Genesis 1:1-5" ``` -------------------------------- ### Get Last Chapter of a Book Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/api-reference/FreeUseBibleApi.md Retrieves the last chapter of a given book, supporting translations, commentaries, and datasets. Returns null if the book has no chapters. Ensure you have a book object from a relevant `get...Books()` method. ```typescript const api = new FreeUseBibleApi(); const books = await api.getTranslationBooks('BSB'); const revelation = books.books[books.books.length - 1]; // Revelation const lastChapter = await api.getLastChapter(revelation); if (lastChapter) { console.log(`Last chapter: ${lastChapter.chapter.number}`); } ``` -------------------------------- ### Customize Free Use Bible API Client Options Source: https://github.com/helloaolab/bible-api/blob/main/packages/free-use-bible-api/README.md Initialize the API client with custom options like endpoint and cache settings. ```typescript import { FreeUseBibleApi } from 'free-use-bible-api'; const api = new FreeUseBibleApi({ endpoint: 'https://bible.helloao.org/', useCache: true, }); ``` -------------------------------- ### getLastChapter() Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/INDEX.md Gets the last chapter of the current book or translation. ```APIDOC ## getLastChapter() ### Description Gets the last chapter of the current book or translation. ### Method SDK Method ### Parameters None explicitly documented for this method signature. ### Response - Returns information about the last chapter. ``` -------------------------------- ### getPreviousChapter() Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/INDEX.md Gets the previous chapter based on the current chapter context. ```APIDOC ## getPreviousChapter() ### Description Gets the previous chapter based on the current chapter context. ### Method SDK Method ### Parameters None explicitly documented for this method signature. ### Response - Returns information about the previous chapter. ``` -------------------------------- ### Example: Formatting a Cross-Chapter Range Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/api-reference/utility-methods.md Demonstrates formatting a reference that spans across two chapters, including specific verses. Assumes a book object is available. ```typescript const crossChapterRange = api.formatReference(genesis, { chapter: 1, verse: 1, endChapter: 2, endVerse: 3 }); console.log(crossChapterRange); // "Genesis 1:1-2:3" ``` -------------------------------- ### Dynamic Configuration Based on Environment Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/configuration.md Create a Bible API instance with endpoints and cache settings dynamically determined by the Node.js environment. Defaults to 'development' if `NODE_ENV` is not set. ```typescript function createBibleApi(env: string = process.env.NODE_ENV || 'development') { const endpoints = { development: 'http://localhost:3000/', staging: 'https://staging-api.example.com/', production: 'https://bible.helloao.org/' }; return new FreeUseBibleApi({ endpoint: endpoints[env] || endpoints.production, useCache: env === 'production' }); } const api = createBibleApi(); ``` -------------------------------- ### Get Commentary for Chapter Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/COMPLETION_REPORT.txt Retrieves the commentary for a specific chapter of a book. ```APIDOC ## GET /api/c/{commentary}/{book}/{chapter}.json ### Description Retrieves the commentary for a specific chapter of a book. ### Method GET ### Endpoint /api/c/{commentary}/{book}/{chapter}.json ### Parameters #### Path Parameters - **commentary** (string) - Required - The identifier of the commentary (e.g., "commentary1"). - **book** (string) - Required - The identifier of the book (e.g., "GEN"). - **chapter** (string) - Required - The chapter number (e.g., "1"). ### Response #### Success Response (200) - **commentaryContent** (object) - An object containing the commentary for the specified chapter. ### Response Example ```json { "commentaryContent": { "chapter": 1, "commentary": "commentary1", "content": "This chapter discusses..." } } ``` ``` -------------------------------- ### Get Complete Translation Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/COMPLETION_REPORT.txt Retrieves the entire content of a Bible translation. ```APIDOC ## GET /api/{translation}/complete.json ### Description Retrieves the entire content of a Bible translation. ### Method GET ### Endpoint /api/{translation}/complete.json ### Parameters #### Path Parameters - **translation** (string) - Required - The identifier of the Bible translation (e.g., "en-ESV"). ### Response #### Success Response (200) - **fullBible** (object) - An object containing all books and chapters for the translation. ### Response Example ```json { "fullBible": { "GEN": { "1": {"verses": [{"verse": 1, "text": "..."}]}, "2": {"verses": [{"verse": 1, "text": "..."}]} } } } ``` ``` -------------------------------- ### Example API Response for /api/c/tyndale/profiles.json Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md This JSON object represents a sample response from the API endpoint for fetching profiles of the 'tyndale' commentary. It includes commentary details and a list of profiles with their associated references. ```json { "commentary": { "id": "tyndale", "name": "Tyndale Open Study Notes", "website": "https://tyndaleopenresources.com/", "licenseUrl": "https://creativecommons.org/licenses/by-sa/4.0/", "licenseNotes": "Changes were made to the content to change the format to JSON to make it compatible with the Free Use Bible API. No changes were made to the content contained in the XML formatting.", "englishName": "Tyndale Open Study Notes", "language": "eng", "textDirection": "rtl", "sha256": "62fa003ca326f8ab22a04accb2a49d2b5865ce2cecd74284228e1be08edd5e10", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/c/tyndale/books.json", "listOfProfilesApiLink": "/api/c/tyndale/profiles.json", "numberOfBooks": 69, "totalNumberOfChapters": 1243, "totalNumberOfVerses": 15757, "totalNumberOfProfiles": 125, "languageName": "English", "languageEnglishName": "English" }, "profiles": [ { "id": "aaron", "reference": { "book": "EXO", "chapter": 4, "verse": 14, "endVerse": 16 }, "subject": "Aaron", "thisProfileLink": "/api/c/tyndale/profiles/aaron.json", "referenceChapterLink": "/api/c/tyndale/EXO/4.json" }, { "id": "abiathar", "reference": { "book": "1SA", "chapter": 22, "verse": 20, "endVerse": 23 }, "subject": "Abiathar", "thisProfileLink": "/api/c/tyndale/profiles/abiathar.json", "referenceChapterLink": "/api/c/tyndale/1SA/22.json" }, ] } ``` -------------------------------- ### Get Commentary Books Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/INDEX.md Retrieves a list of books covered by a specific commentary. ```APIDOC ## GET /api/c/{commentary}/books.json ### Description Retrieves a list of books covered by a specific commentary. ### Method GET ### Endpoint /api/c/{commentary}/books.json ### Parameters #### Path Parameters - **commentary** (string) - Required - The abbreviation of the commentary (e.g., 'cob'). ### Response #### Success Response (200) - **books** (array) - A list of book objects covered by the commentary. ### Response Example { "example": "{\"books\":[{\"name\":\"Genesis\",\"abbr\":\"gen\"}]}" ``` -------------------------------- ### Example: Formatting a Single Verse Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/api-reference/utility-methods.md Demonstrates how to use `formatReference` to format a single verse reference. Requires fetching translation books and selecting a specific book. ```typescript const api = new FreeUseBibleApi(); const books = await api.getTranslationBooks('BSB'); const genesis = books.books[0]; const ref = api.formatReference(genesis, { chapter: 1, verse: 1 }); console.log(ref); // "Genesis 1:1" ``` -------------------------------- ### Get Translation Books Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/INDEX.md Retrieves a list of books for a specified Bible translation. ```APIDOC ## GET /api/{translation}/books.json ### Description Retrieves a list of books for a specified Bible translation. ### Method GET ### Endpoint /api/{translation}/books.json ### Parameters #### Path Parameters - **translation** (string) - Required - The abbreviation of the translation (e.g., 'kjv', 'niv'). ### Response #### Success Response (200) - **books** (array) - A list of book objects, each with 'name', 'abbr', and 'chapters' properties. ### Response Example { "example": "{\"books\":[{\"name\":\"Genesis\",\"abbr\":\"gen\",\"chapters\":50},{\"name\":\"Exodus\",\"abbr\":\"ex\",\"chapters\":40}]}" ``` -------------------------------- ### Get Books in a Commentary Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/COMPLETION_REPORT.txt Retrieves a list of all books available for a specific commentary. ```APIDOC ## GET /api/c/{commentary}/books.json ### Description Retrieves a list of all books available for a specific commentary. ### Method GET ### Endpoint /api/c/{commentary}/books.json ### Parameters #### Path Parameters - **commentary** (string) - Required - The identifier of the commentary (e.g., "commentary1"). ### Response #### Success Response (200) - **books** (array) - A list of book objects, each containing an ID and name. ### Response Example ```json { "books": [ {"id": "GEN", "name": "Genesis"}, {"id": "EXO", "name": "Exodus"} ] } ``` ``` -------------------------------- ### Get Available Datasets Source: https://github.com/helloaolab/bible-api/blob/main/docs/guide/making-requests.md Fetches a list of all available datasets supported by the API. ```APIDOC ## GET /api/available_datasets.json ### Description Retrieves a list of all available datasets. ### Method GET ### Endpoint /api/available_datasets.json ### Response #### Success Response (200) - **availableDatasets** (array) - A list of available dataset objects. ``` -------------------------------- ### Example API Response for Books Source: https://github.com/helloaolab/bible-api/blob/main/docs/reference/README.md Illustrates the JSON structure returned by the `/api/{translation}/books.json` endpoint, showing translation details and a list of books. ```json { "translation": { "id": "BSB", "name": "Berean Standard Bible", "website": "https://berean.bible/", "licenseUrl": "https://berean.bible/", "shortName": "BSB", "englishName": "Berean Standard Bible", "language": "eng", "textDirection": "ltr", "availableFormats": [ "json" ], "listOfBooksApiLink": "/api/BSB/books.json", "numberOfBooks": 66, "totalNumberOfChapters": 1189, "totalNumberOfVerses": 31086, "languageName": "English", "languageEnglishName": "English" }, "books": [ { "id": "GEN", "translationId": "BSB", "name": "Genesis", "commonName": "Genesis", "title": "Genesis", "order": 1, "numberOfChapters": 50, "firstChapterNumber": 1, "firstChapterApiLink": "/api/BSB/GEN/1.json", "lastChapterNumber": 50, "lastChapterApiLink": "/api/BSB/GEN/50.json", "totalNumberOfVerses": 1533 }, ] } ``` -------------------------------- ### Get Available Commentaries Source: https://github.com/helloaolab/bible-api/blob/main/docs/guide/making-requests.md Fetches a list of all available commentaries supported by the API. ```APIDOC ## GET /api/available_commentaries.json ### Description Retrieves a list of all available commentaries. ### Method GET ### Endpoint /api/available_commentaries.json ### Response #### Success Response (200) - **availableCommentaries** (array) - A list of available commentary objects. ``` -------------------------------- ### Accessing and Setting the API Endpoint Source: https://github.com/helloaolab/bible-api/blob/main/_autodocs/api-reference/FreeUseBibleApi.md Demonstrates how to access the default API endpoint and how to set a custom endpoint for the FreeUseBibleApi. Ensure the custom endpoint is a valid URL. ```typescript const api = new FreeUseBibleApi(); console.log(api.endpoint); // "https://bible.helloao.org/" api.endpoint = 'https://custom-bible-api.com/'; ``` -------------------------------- ### Get a Chapter from a Translation Source: https://github.com/helloaolab/bible-api/blob/main/docs/guide/making-requests.md Fetches a specific chapter from a given book and translation. ```APIDOC ## GET /api/{translation}/{book}/{chapter}.json ### Description Retrieves a specific chapter from a given book and translation. ### Method GET ### Endpoint /api/{translation}/{book}/{chapter}.json ### Parameters #### Path Parameters - **translation** (string) - Required - The identifier for the Bible translation (e.g., BSB). - **book** (string) - Required - The identifier for the book (e.g., GEN). - **chapter** (integer) - Required - The chapter number. ### Response #### Success Response (200) - **chapter** (object) - An object containing the chapter's content and metadata. ```