Developer Tools: API

Application Programming Interface (API)

Getting Started

Once you have an API key for your application, this Getting Started guide will get you up and running with the Bible Search API in a few simple steps. The examples on this page use cURL, both with the command-line utility and via PHP's support for libcurl. You will need to install cURL to use the command-line examples and PHP cURL support to use the PHP examples. Many hosts provide libcurl support in PHP automatically, so you may already be set up. You will also need the SimpleXML PHP module, which is included in PHP by default.

Getting a Verse

The first thing we'll do is retrieve a specific verse. Let's get Acts 8:34 in the GNT translation. We'll use the Show action on the verses resource, which we can do via this URL:

https://bibles.org/v2/verses/eng-GNTD:Acts.8.34.xml

Here's the command needed to use command-line cURL to retrieve the verse:

curl -L -u #{API Token}:X -k https://bibles.org/v2/verses/eng-GNTD:Acts.8.34.xml

Note: don't forget to replace #{API Token} with your application's API token in all of the examples on this page.

A couple of things to notice about this example: first, you see that the -L option is used, which tells cURL to follow redirects. The Bible Search API sometimes uses redirects, so it's important to include this option. Second, notice that we use the -u option to specify a username and password. Authentication is done on the Bible Search API with HTTP Basic authentication and your application's API token is given as the username. The password is ignored by the server, so you can put whatever you want; the examples on this page just use an "X" for the password. Third, the -k option is used to tell cURL to not verify the SSL certificate. On many systems cURL calls may fail without this option even when the SSL certificate is valid.

Here's how to retrieve the same verse in PHP:

<?php
$token = '#{API Token}';
$url = 'https://bibles.org/v2/verses/eng-GNTD:Acts.8.34.xml';

// Set up cURL
$ch = curl_init();
// Set the URL
curl_setopt($ch, CURLOPT_URL, $url);
// don't verify SSL certificate
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
// Return the contents of the response as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Follow redirects
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
// Set up authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$token:X");

// Do the request
$response = curl_exec($ch);
curl_close($ch);

print($response);
?>

In the PHP example, we use several curl_setopt() calls to set the cURL options we need, request the XML from the server, then print it out.

Both of the above examples will print the returned XML, like this:

<?xml version="1.0" encoding="utf-8" ?>
<response><verses><verse id='eng-GNTD:Acts.8.34'><auditid>0</auditid><verse>34</verse><lastverse>34</lastverse><id>eng-GNTD:Acts.8.34</id><osis_end>eng-GNTD:Acts.8.34</osis_end><label></label><reference>Acts 8:34</reference><text><![CDATA[<p class="p"><sup id="Acts.8.34" class="v">34</sup>The official asked Philip, “Tell me, of whom is the prophet saying this? Of himself or of someone else?”</p>]]></text><parent><chapter id='eng-GNTD:Acts.8'><path>/chapters/eng-GNTD:Acts.8</path><name>Acts 8</name><id>eng-GNTD:Acts.8</id></chapter></parent><next><verse id='eng-GNTD:Acts.8.35'><path>/verses/eng-GNTD:Acts.8.35</path><name>Acts 8:35</name><id>eng-GNTD:Acts.8.35</id></verse></next><previous><verse id='eng-GNTD:Acts.8.32'><path>/verses/eng-GNTD:Acts.8.32</path><name>Acts 8:32</name><id>eng-GNTD:Acts.8.32</id></verse></previous><copyright><![CDATA[<p>Good News Translation (Today’s English Version, Second Edition) © 1992 American Bible Society. All rights reserved.</p>]]></copyright></verse></verses><meta><fums><![CDATA[<script>
var _BAPI=_BAPI||{};
if(typeof(_BAPI.t)==='undefined'){
document.write('\x3Cscript src="'+document.location.protocol+'//d2ue49q0mum86x.cloudfront.net/include/fums.c.js"\x3E\x3C/script\x3E');}
document.write("\x3Cscript\x3E_BAPI.t('516ec91433b034.36359300');\x3C/script\x3E");
</script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=516ec91433b034.36359300" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums><fums_tid>516ec91433b034.36359300</fums_tid><fums_js_include>d2ue49q0mum86x.cloudfront.net/include/fums.c.js</fums_js_include><fums_js><![CDATA[var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('516ec91433b034.36359300'); }]]></fums_js><fums_noscript><![CDATA[<img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=516ec91433b034.36359300" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" />]]></fums_noscript></meta></response>

When formatted, the response looks like this:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <verses>
    <verse id="eng-GNTD:Acts.8.34">
      <auditid>0</auditid>
      <verse>34</verse>
      <lastverse>34</lastverse>
      <id>eng-GNTD:Acts.8.34</id>
      <osis_end>eng-GNTD:Acts.8.34</osis_end>
      <label/>
      <reference>Acts 8:34</reference>
      <text><![CDATA[<p class="p"><sup id="Acts.8.34" class="v">34</sup>The official asked Philip, “Tell me, of whom is the prophet saying this? Of himself or of someone else?”</p>]]></text>
      <parent>
        <chapter id="eng-GNTD:Acts.8">
          <path>/chapters/eng-GNTD:Acts.8</path>
          <name>Acts 8</name>
          <id>eng-GNTD:Acts.8</id>
        </chapter>
      </parent>
      <next>
        <verse id="eng-GNTD:Acts.8.35">
          <path>/verses/eng-GNTD:Acts.8.35</path>
          <name>Acts 8:35</name>
          <id>eng-GNTD:Acts.8.35</id>
        </verse>
      </next>
      <previous>
        <verse id="eng-GNTD:Acts.8.32">
          <path>/verses/eng-GNTD:Acts.8.32</path>
          <name>Acts 8:32</name>
          <id>eng-GNTD:Acts.8.32</id>
        </verse>
      </previous>
      <copyright><![CDATA[<p>Good News Translation (Today’s English Version, Second Edition) © 1992 American Bible Society. All rights reserved.</p>]]></copyright>
    </verse>
  </verses>
  <meta>
    <fums><![CDATA[<script>
var _BAPI=_BAPI||{};
if(typeof(_BAPI.t)==='undefined'){
document.write('\x3Cscript src="'+document.location.protocol+'//d2ue49q0mum86x.cloudfront.net/include/fums.c.js"\x3E\x3C/script\x3E');}
document.write("\x3Cscript\x3E_BAPI.t('516ec93969e026.45627602');\x3C/script\x3E");
</script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=516ec93969e026.45627602" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums>
    <fums_tid>516ec93969e026.45627602</fums_tid>
    <fums_js_include>d2ue49q0mum86x.cloudfront.net/include/fums.c.js</fums_js_include>
    <fums_js><![CDATA[var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('516ec93969e026.45627602'); }]]></fums_js>
    <fums_noscript><![CDATA[<img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=516ec93969e026.45627602" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" />]]></fums_noscript>
  </meta>
</response>

Extracting the Text

Now that we have the verse, let's use PHP to extract the text of the verse from the response. We'll use the SimpleXML PHP extension for XML parsing. Here's our previous PHP code with two lines at the end that extract and print just the verse text:

<?php
$token = '#{API Token}';
$url = 'https://bibles.org/v2/verses/eng-GNTD:Acts.8.34.xml';

// Set up cURL
$ch = curl_init();
// Set the URL
curl_setopt($ch, CURLOPT_URL, $url);
// don't verify SSL certificate
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
// Return the contents of the response as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Follow redirects
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
// Set up authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "$token:X");

// Do the request
$response = curl_exec($ch);
curl_close($ch);

// Parse the XML into a SimpleXML object
$xml = new SimpleXMLElement($response);

// Print the text from the 0th verse
print ($xml->verses->verse[0]->text);
?>

This script will output the following:

<p class="p"><sup id="Acts.8.34" class="v">34</sup>The official asked Philip, “Tell me, of whom is the prophet saying this? Of himself or of someone else?”</p>

Next Steps

Now that you've got the basics down, where do you go from here?

First, take a look at the rest of the API documentation. Play around with the code on this page and combine it with the other API actions to get what you want. Finally, integrate the results with your website or application.

Soon you and your users will be interacting with the Bible in completely new ways through the ABS Bible Search API.