Developer Tools: API

Widget

Create

Highlighter - Beta

API

Application Programming Interface (API)

Searching

The BibleSearch API provides a general search.xml GET endpoint. It accepts a query parameter that can be either a passage or a keyword and will automatically figure out what kind of query you've given it. If it's a keyword search, the results will be the same as a keyword search on the website: the parser performs stemming and also takes into account users' tags and "Was this helpful?" votes.

Note: it's important to follow redirects when using the search.xml endpoint. Depending on the query used, it will redirect to the appropriate results url.

Response Format

The response format looks like this:

<search>
  <result>
    <type>TYPE</type>
    <summary>
      [...]
    </summary>
    <spelling>
      [...]
    </spelling>
    <TYPE>
      [...]
    </TYPE>
  </result>
</search>

Every result has a search element, which contains a result element.

The type tells you the type of the result and specifies the name of the element containing the results of the query.

The summary element contains information about the query, such as versions searched, sort order, testaments searched, number of results, etc.

The spelling element contains spelling suggestions, if there are any.

TYPE is not an element name, but is an element named after the type of results. For example, if the query was determined to be a passage search, the response will look like this:

<search>
  <result>
    <type>passages</type>
    <summary>
      [...]
    </summary>
    <spelling>
      [...]
    </spelling>
    <passages>
      [...]
    </passages>
  </result>
</search>

In this case, the passages element contains a set of passage elements that are the results of the query. Each passage element contains information about a single passage that matches the query.

Simple Query

GET /search.xml?query=#{query}

The simplest search you can do is to just specify a query parameter. This will return results in all available versions.

Example:

Request

GET https://biblesearch.americanbible.org/search.xml?query=Mahershalalhashbaz

This will resolve to a keyword query and yield a response like:

Response

<?xml version="1.0" encoding="utf-8"?>
<search>
  <result>
    <type>verses</type>
    <summary>
      <query>Mahershalalhashbaz</query>
      <start>1</start>
      <total>2</total>
      <rpp>15</rpp>
      <sort>relevance</sort>
      <versions>
        <version>GNT</version>
        <version>KJV</version>
        <version>CEV</version>
        <version>RVR60</version>
      </versions>
      <testaments>
        <testament>OT</testament>
        <testament>NT</testament>
      </testaments>
    </summary>
    <spelling>
      <entries>
        <entry>
          <query>Mahershalalhashbaz</query>
          <suggestions>
            <suggestion>boaz</suggestion>
            <suggestion>bad</suggestion>
          </suggestions>
        </entry>
      </entries>
    </spelling>
    <verses>
      <verse id='CEV:Isa.8.3'>
        <auditid>0</auditid>
        <verse>3</verse>
        <lastverse>3</lastverse>
        <id>CEV:Isa.8.3</id>
        <osis_end>CEV:Isa.8.3</osis_end>
        <label>Isa.008.003,CEV</label>
        <text>
          <![CDATA[<span class="para"><span class="v23_8_3"><sup class="v23_8_3">3</sup>Sometime later, my wife and I had a son, and the <span class="divineName"><span class='divineCaps'>L</span>ORD</span> said, “Name him Maher-Shalal-Hash-Baz.</span></span>]]>
        </text>
        <reference>Isaiah 8:3</reference>
        <parent>
          <chapter id='CEV:Isa.8'>
            <path>/chapters/CEV:Isa.8</path>
            <name>Isaiah 8</name>
            <id>CEV:Isa.8</id>
          </chapter>
        </parent>
        <next>
          <verse id='CEV:Jer.1.1'>
            <path>/verses/CEV:Jer.1.1</path>
            <name>Jeremiah 1:1</name>
            <id>CEV:Jer.1.1</id>
          </verse>
        </next>
        <previous>
          <verse id='CEV:Song.1.1'>
            <path>/verses/CEV:Song.1.1</path>
            <name>Song of Solomon 1:1</name>
            <id>CEV:Song.1.1</id>
          </verse>
        </previous>
        <copyright>
          <![CDATA[Copyright 2006, American Bible Society]]>
        </copyright>
      </verse>
    </verses>
  </result>
</search>

Example for "John 3:16":

Request

https://biblesearch.americanbible.org/search.xml?query=john+3:16

This will be resolved to a passage query and will yield a response like:

Response

<?xml version="1.0" encoding="utf-8"?>
<search>
  <result>
    <type>passages</type>
    <passages>
      <passage>
        <display>John 3:16</display>
        <version>GNT</version>
        <path>/chapters/GNT:John.3/verses.xml?start=16&end=16</path>
        <text_preview>
          <![CDATA[<span class="para"><span class="v43_3_16"><sup class="v43_3_16">16</sup>For God loved the world so much that he gave his only Son, so that everyone who believes in him may not die but have eternal life.
          </span></span> ]]>
        </text_preview>
        <chapter_id>GNT:John.3</chapter_id>
        <start_verse>16</start_verse>
        <end_verse>16</end_verse>
      </passage>
      <passage>
        <display>John 3:16</display>
        <version>KJV</version>
        <path>/chapters/KJV:John.3/verses.xml?start=16&end=16</path>
        <text_preview>
          <![CDATA[<span class="para"><span class="v43_3_16"><sup class="v43_3_16">16</sup>For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life.</span></span> ]]>
        </text_preview>
        <chapter_id>KJV:John.3</chapter_id>
        <start_verse>16</start_verse>
        <end_verse>16</end_verse>
      </passage>
      <passage>
        <display>John 3:16</display>
        <version>CEV</version>
        <path>/chapters/CEV:John.3/verses.xml?start=16&end=16</path>
        <text_preview>
          <![CDATA[<ul><li><span class="para"><span class="v43_3_16"><sup class="v43_3_16">16</sup>God loved the people of this world so much that he gave his only Son, so that everyone who has faith in him will have eternal life and never really die.</span></span></li></ul> ]]>
        </text_preview>
        <chapter_id>CEV:John.3</chapter_id>
        <start_verse>16</start_verse>
        <end_verse>16</end_verse>
      </passage>
      <passage>
        <display>San Juan 3:16</display>
        <version>RVR60</version>
        <path>/chapters/RVR60:John.3/verses.xml?start=16&end=16</path>
        <text_preview>
          <![CDATA[<span class="para"><span class="v43_3_16"><sup class="v43_3_16">16</sup>Porque de tal manera amó Dios al mundo, que ha dado a su Hijo unigénito, para que todo aquel que en él cree, no se pierda, mas tenga vida eterna. </span></span> ]]>
        </text_preview>
        <chapter_id>RVR60:John.3</chapter_id>
        <start_verse>16</start_verse>
        <end_verse>16</end_verse>
      </passage>
    </passages>
  </result>
</search>

Specifying Versions and Advanced Queries

GET /search.xml?query=#{query}&version=#{version_id_list}

The query can include a version specifier of one or more desired versions to search across. The available version IDs can be listed with the versions endpoint. If the search is a keyword search, you may use the modifiers (e.g., precision, spelling, exclude, etc.) specified in the Verses search section.

To specify a single version, add &version=ID.

Example:

Request

GET https://biblesearch.americanbible.org/search.xml?query=john+3:16&version=KJV

Response

<?xml version="1.0" encoding="utf-8"?>
<search>
  <result>
    <type>passages</type>
    <passages>
      <passage>
        <display>John 3:16</display>
        <version>KJV</version>
        <path>/chapters/KJV:John.3/verses.xml?start=16&end=16</path>
        <text_preview>
          <![CDATA[<span class="para"><span class="v43_3_16"><sup class="v43_3_16">16</sup>For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life.</span></span> ]]>
        </text_preview>
        <chapter_id>KJV:John.3</chapter_id>
        <start_verse>16</start_verse>
        <end_verse>16</end_verse>
      </passage>
    </passages>
  </result>
</search>

To specify multiple versions, use a comma-separated list of IDs.

Example:

Request

GET https://biblesearch.americanbible.org/search.xml?query=john+3:16&version=KJV,CEV,GNT

Response

<?xml version="1.0" encoding="utf-8"?>
<search>
  <result>
    <type>passages</type>
    <passages>
      <passage>
        <display>John 3:16</display>
        <version>KJV</version>
        <path>/chapters/KJV:John.3/verses.xml?start=16&end=16</path>
        <text_preview>
          <![CDATA[<span class="para"><span class="v43_3_16"><sup class="v43_3_16">16</sup>For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life.</span></span> ]]>
        </text_preview>
        <chapter_id>KJV:John.3</chapter_id>
        <start_verse>16</start_verse>
        <end_verse>16</end_verse>
      </passage>
      <passage>
        <display>John 3:16</display>
        <version>CEV</version>
        <path>/chapters/CEV:John.3/verses.xml?start=16&end=16</path>
        <text_preview>
          <![CDATA[<ul><li><span class="para"><span class="v43_3_16"><sup class="v43_3_16">16</sup>God loved the people of this world so much that he gave his only Son, so that everyone who has faith in him will have eternal life and never really die.</span></span></li></ul> ]]>
        </text_preview>
        <chapter_id>CEV:John.3</chapter_id>
        <start_verse>16</start_verse>
        <end_verse>16</end_verse>
      </passage>
      <passage>
        <display>John 3:16</display>
        <version>GNT</version>
        <path>/chapters/GNT:John.3/verses.xml?start=16&end=16</path>
        <text_preview>
          <![CDATA[<span class="para"><span class="v43_3_16"><sup class="v43_3_16">16</sup>For God loved the world so much that he gave his only Son, so that everyone who believes in him may not die but have eternal life.
          </span></span> ]]>
        </text_preview>
        <chapter_id>GNT:John.3</chapter_id>
        <start_verse>16</start_verse>
        <end_verse>16</end_verse>
      </passage>
    </passages>
  </result>
</search>