americanbible / biblesearch-api-js

Use the ABS api from javascript. This is built for phonegap/cordova use, but can be added in a regular web ap.

biblesearch-api-js

The American Bible Society has produced this javascript library to ease the use of the Bible Search api (http://bibles.org/pages/api) in web/cordova/phonegap applications. The api (and this library) allow you to easily:

• search the Bible
• locate specific passages
• get information about specific books, chapters, and verses
• do all that in one or more versions
• store nothing locally

In addition ABS manages the version copyright requirements and keeps the textual data up to date with latest changes by the copyright owners/publishers. Use of this library and the api is free to the public for non-commercial use. See http://bibles.org/pages/api for additional information.

Installation

To install this plugin in a cordova/phonegap app, follow the Command-line Interface Guide.

cordova plugin add https://github.com/americanbible/biblesearch-api-js.git

If you are not using the Cordova Command-line Interface, follow Using Plugman to Manage Plugins.

plugman --platform ios --project platforms/ios/ --plugin https://github.com/americanbible/biblesearch-api-js.git

This plugin does have a small dependency on the Cordova Network Manager. Starting in cordova version 3.0 this is not bundled with cordova apps by default so you'll want to install it to:

cordova plugin add https://github.com/apache/cordova-plugin-network-information.git

If you want to use this in a non-cordova web app then just include the script appropriately for your application. It can be easily loaded via require.js with no problems, or just add it via a standard script tag wherever you want. The script will create an object at plugins.absBiblesearch (which is normal for phonegap).

You will also need to get a free api key at http://bibles.org/pages/api/signup.

Usage

In your javascript:

var bsearch = plugins.absBiblesearch; // just to make access easier.
bsearch.setKey(/*your API key goes here*/); // just do this once in your app initialization

// at this point you are ready to make api calls.
if (!bsearch.versionsByLanguage('eng-US', function(data) {
	// data will now contain a JSON object.  To see an example of the content see the api documentation.
    for (var i = 0; i < data.response.versions.length; i++) {
        var version = data.response.versions[i];
        alert(version.version + ': ' + version.name);
    }
})) {
    alert('error: ' + bsearch.lastError());
}

API & Key

You can get additional details on the api at http://bibles.org/pages/api.

Comments and Complaints

If you have any issues you can let us know by email at [email protected].

Changelog

v1.0.5 - Fix for ios. Auth header wasn't going through in some cases, so we're going low-tech. Works in ios and safari.

v1.0.4 - Update for cordova v3 plugin architecture.

v1.0.3 - Fix asynchronous credential issue

biblesearch-api-js's Issues

Question about API Key and security

Hello,
I'd like to use your API in a bible search tool I'm making in NodeJS. It's meant for consumption by everyday users, but it's distributed as an npm package. So while the package is running in NodeJS, it's a user client, and not a server. I therefore need to distribute an API key with the package, which means it's accessible to anyone. That hurts me in my developer bones, but is it actually an issue in this case? Are there any alternatives?

Thanks,
Daniel Hines

Grunt, tests, and structure

Would you be opposed to the addition of Grunt of Gulp to this repository? I'm interested in adding a Gruntfile to automate some aspects of this package including minification and make it easy to add and integrate tests as well.

I also have some ideas about the structure of the main JS file and am curious if you'd be willing to do some re-organization so the library can work well as a node.js module, too.