Developer Tools: API

Widget

Create

Highlighter - Beta

API

Application Programming Interface (API)

FUMS

FUMS is the Fair Use Management System. It's a system that we ask all API developers to use as a way to help us ensure that the API contents are being used fairly. It also allows us to profile usage of the various versions, books, chapters, and verses that are requested from the API, so that we can communicate the value of API-accessible Scripture texts back to copyright holders and publishers. You can read more background on why the FUMS exists in the API Introduction.

How Do I Use It?

Using the FUMS is simple. Each API response will include a meta element as the final child of the initial container. That meta element will contain a fums element which will have CDATA-encoded JavaScript and HTML that can be added to any webpage or email message.

Here's a request/response listing showing a request for Acts 8 from the KJV.

Request

GET https://biblesearch.americanbible.org/chapters/KJV:Acts.8.xml

Response

<?xml version="1.0" encoding="utf-8"?>
<chapters>
    <chapter id="KJV:Acts.8">
        <auditid>0</auditid>
        <label/>
        <text><![CDATA[<span class="para"><span class="v44_8_1"><sup class="v44_8_1">1</sup>And Saul was consenting unto his death.</span></span> [ remaining scripture snipped for brevity ]</text>
        <chapter>8</chapter>
        <id>KJV:Acts.8</id>
        <osis_end>KJV:Acts.8040</osis_end>
        <parent>
            <book id="KJV:Acts">
                <path>/books/KJV:Acts</path>
                <name>Acts</name>
                <id>KJV:Acts</id>
            </book>
        </parent>
        <next>
            <chapter id="KJV:Rom.1">
                <path>/chapters/KJV:Rom.1</path>
                <name>Romans 1</name>
                <id>KJV:Rom.1</id>
            </chapter>
        </next>
        <previous>
            <chapter id="KJV:John.21">
                <path>/chapters/KJV:John.21</path>
                <name>John 21</name>
                <id>KJV:John.21</id>
            </chapter>
        </previous>
        <copyright><![CDATA[The King James Version is public domain. Copy and distribute freely.]]></copyright>
    </chapter>
    <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('4d2ca3cf152707.75835067');\x3C/script\x3E");
</script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=4d2ca3cf152707.75835067" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums>
    </meta>
</chapters>

In the example above, note the section in bold. This is the FUMS data. When your application makes an API request and displays it on a webpage, it should always also display the contents of the meta/fums node as well. You don't need to do anything special with the contents of that node, and it can appear anywhere in your HTML. When your visitors load a page on your site that includes FUMS code, it will run automatically.

Can I See An Example?

Let's assume your application has made a request to the API for Acts 8 (as seen above) and has assembled it into a webpage. Here's what that HTML might look like, including the FUMS code:

HTML

<!DOCTYPE html>
<html>
<head>
    <title>Acts 8 (KJV) :: My Site</title>
</head>
<body>
    <h1>Acts 8 (KJV)</h1>
    <div>
    <span class="para"><span class="v44_8_1"><sup class="v44_8_1">1</sup>And Saul was consenting unto his death.</span></span> 
    <span class="title-passage"><span>Saul Persecutes the Church</span></span> 
    <span class="para"><span class="v44_8_1">And at that time there was a great persecution against the church which was at Jerusalem; and they were all scattered abroad throughout the regions of Judea and Samaria, except the apostles. </span>
    [ remaining scripture removed for brevity ]
    </span>
    </div>
    <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('4d2ca3cf152707.75835067');\x3C/script\x3E");
</script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=4d2ca3cf152707.75835067" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>
</body>
</html>

The section in bold is included directly from the API response, and is placed anywhere in the HTML document.

What Does FUMS do?

The FUMS code sent back with each API response includes a small snippet of JavaScript code that will load the FUMS library and log the usage of the API data. It also includes a fallback non-JavaScript option in case a user's browser or email reader does not execute JavaScript.

Will It Affect Performance?

FUMS has been designed to have no noticeable impact on your site's load time. We have carefully optimized the JavaScript code itself to minimize its size, and we deliver it from a geographically-aware content delivery network (CDN). The JavaScript code is lightweight in execution, and will not alter the look or feel of your website in any way.

What Kind Of Information Do You Collect?

FUMS collects information about the scripture data that is used on your website. Additionally, it collects anonymous usage information. It does not log your site's URL or any identifying information about you or your visitor.

What If I'm Displaying Multiple API Responses At Once?

No problem! Just include the contents of the meta/fums node for each API response that you're displaying, all on the same page. Our library is smart enough to only load itself once, and it is programmed to efficiently log data even when multiple API responses are used on a single page. FUMS will run efficiently for one, twenty, or hundreds of API responses on a single HTML page.

American Bible Society