Getting Started

Once you have your API key, this Getting Started guide will get you up and running with the BibleSearch 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://biblesearch.americanbible.org/verses/GNT: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://biblesearch.americanbible.org/verses/GNT:Acts.8.34.xml

Note: don't forget to replace #{API Token} with your own 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 BibleSearch 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 BibleSearch API with HTTP Basic authentication and your 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://biblesearch.americanbible.org/verses/GNT: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" ?>
<verses><verse id='GNT:Acts.8.34'><auditid>0</auditid><verse>34</verse><lastverse>34</lastverse><id>GNT:Acts.8.34</id><osis_end>GNT:Acts.8.34</osis_end><label></label><text><![CDATA[<span class="para"><span class="v44_8_34"><sup class="v44_8_34">34</sup>The official asked Philip,  
          “Tell me, of whom is the prophet saying this? Of himself or of someone else?”
          </span></span>]]></text><reference>Acts 8:34</reference><parent><chapter id='GNT:Acts.8'><path>/chapters/GNT:Acts.8</path><name>Acts 8</name><id>GNT:Acts.8</id></chapter></parent><next><verse id='GNT:Rom.11.23'><path>/verses/GNT:Rom.11.23</path><name>Romans 11:23</name><id>GNT:Rom.11.23</id></verse></next><previous><verse id='GNT:John.14.1'><path>/verses/GNT:John.14.1</path><name>John 14:1</name><id>GNT:John.14.1</id></verse></previous><copyright><![CDATA[Scripture taken from the Good News Translation in Today's English Version- Second Edition Copyright © 1992 by American Bible Society. Used by Permission.]]></copyright></verse></verses>

When formatted, the response looks like this:

<?xml version="1.0" encoding="utf-8"?>
<verses>
  <verse id='GNT:Acts.8.34'>
    <auditid>0</auditid>
    <verse>34</verse>
    <lastverse>34</lastverse>
    <id>GNT:Acts.8.34</id>
    <osis_end>GNT:Acts.8.34</osis_end>
    <label></label>
    <text>
      <![CDATA[<span class="para"><span class="v44_8_34"><sup class="v44_8_34">34</sup>The official asked Philip,  
          “Tell me, of whom is the prophet saying this? Of himself or of someone else?”
          </span></span>]]>
    </text>
    <reference>Acts 8:34</reference>
    <parent>
      <chapter id='GNT:Acts.8'>
        <path>/chapters/GNT:Acts.8</path>
        <name>Acts 8</name>
        <id>GNT:Acts.8</id>
      </chapter>
    </parent>
    <next>
      <verse id='GNT:Rom.11.23'>
        <path>/verses/GNT:Rom.11.23</path>
        <name>Romans 11:23</name>
        <id>GNT:Rom.11.23</id>
      </verse>
    </next>
    <previous>
      <verse id='GNT:John.14.1'>
        <path>/verses/GNT:John.14.1</path>
        <name>John 14:1</name>
        <id>GNT:John.14.1</id>
      </verse>
    </previous>
    <copyright>
      <![CDATA[Scripture taken from the Good News Translation in Today's English Version- Second Edition Copyright © 1992 by American Bible Society. Used by Permission.]]>
    </copyright>
  </verse>
</verses>

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://biblesearch.americanbible.org/verses/GNT: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->verse[0]->text);
?>

This script will output the following:

<span class="para"><span class="v44_8_34"><sup class="v44_8_34">34</sup>The official asked Philip,  
          “Tell me, of whom is the prophet saying this? Of himself or of someone else?”
          </span></span>

Adding a Note

Now that we've gotten the verse, let's add a note to it. Here's how to do that with command-line cURL:

curl -u #{API Token}:X -k -X POST \
-H 'Content-Type: application/xml' -d '<note><title>The Eunuch</title><content>The eunuch questions Philip.</content><references><reference><start>GNT:Acts.8.34</start><end>GNT:Acts.8.34</end></reference></references></note>' \
https://biblesearch.americanbible.org/notes.xml

Here's the same thing in PHP:

<?php

$token = '#{API Token}';
$url = 'https://biblesearch.americanbible.org/notes.xml';

$noteXML = 
'<note>
    <title>The Eunuch</title>
    <content>The eunuch questions Philip.</content>
    <references>
        <reference>
            <start>GNT:Acts.8.34</start>
            <end>GNT:Acts.8.34</end>
        </reference>
    </references>
</note>';

// 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 a POST
curl_setopt($ch, CURLOPT_POST, 1);
// Set the content type
curl_setopt($ch, CURLOPT_HTTPHEADER, Array('Content-Type: application/xml'));
// Add the POST data
curl_setopt($ch, CURLOPT_POSTFIELDS, $noteXML);

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

print($response);
?>

Both of the above will add a new note to the verse and print the response, which contains the details of the note that was created:

<?xml version="1.0" encoding="utf-8" ?>
<notes><note id='187'><id>187</id><user_id>1470</user_id><title>The Eunuch</title><content>The eunuch questions Philip.</content><public>0</public><created_at>2010-11-02 14:54:46</created_at><updated_at>2010-11-02 14:54:46</updated_at><moderated></moderated><references><reference><start>GNT:Acts.8.34</start><end>GNT:Acts.8.34</end></reference></references></note></notes>

Formatted, the response looks like this:

<?xml version="1.0" encoding="utf-8"?>
<notes>
  <note id='187'>
    <id>187</id>
    <user_id>1470</user_id>
    <title>The Eunuch</title>
    <content>The eunuch questions Philip.</content>
    <public>0</public>
    <created_at>2010-11-02 14:54:46</created_at>
    <updated_at>2010-11-02 14:54:46</updated_at>
    <moderated></moderated>
    <references>
      <reference>
        <start>GNT:Acts.8.34</start>
        <end>GNT:Acts.8.34</end>
      </reference>
    </references>
  </note>
</notes>

Deleting the Note

Now let's delete the note we just created. When we created the note, the response contained an ID of 187. We'll need to put this in our delete URL to specify which note to delete. Here's the command-line cURL command we need:

curl -u #{API Token}:X -k -X DELETE https://biblesearch.americanbible.org/notes/187.xml

Notice we're using the DELETE HTTP request method here. Here's the same thing in PHP:

<?php

$token = '#{API Token}';
$url = 'https://biblesearch.americanbible.org/notes/187.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 a DELETE
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

// Do the request
$response = curl_exec($ch);
$responseCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($responseCode === 200) {
    print("Note deleted successfully.\n");
} else {
    print("Note was not deleted.\n");
}

?>

The delete actions on the BibleSearch API don't return XML, so we have to check the HTTP response code to find out if the deletion was successful.

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 BibleSearch API.