Developer Tools: API

Application Programming Interface (API)


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 a child of the initial container. That meta element will contain several fums elements which are intended for different uses of the API.

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

<?xml version="1.0" encoding="utf-8"?>
    <chapter id="eng-KJVA:Acts.8">
      <text><![CDATA[<span class="v44_8_1"> <sup class="v44_8_1">1</sup> And Saul was consenting unto his death. 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 Judæa and Samaria, except the apostles.</span><span class="v44_8_2"> <sup class="v44_8_2">2</sup> And devout men carried Stephen to his burial, and made great lamentation over him.</span><span class="v44_8_3"> <sup class="v44_8_3">3</sup> As for Saul, he made havock of the church, entering into every house, and haling men and women committed them to prison.</span><span class="title-passage"><span>The Church in Judæa and Samaria</span></span><span class="para"><span class="v44_8_4"> <sup class="v44_8_4">4</sup> Therefore they that were scattered abroad went every where preaching the word.</span><span class="v44_8_5"> <sup class="v44_8_5">5</sup> Then Philip went down to the city of Samaria, and preached Christ unto them.</span><span class="v44_8_6"> <sup class="v44_8_6">6</sup> And the people with one accord gave heed unto those things which Philip spake, hearing and seeing the miracles which he did.</span><span class="v44_8_7"> <sup class="v44_8_7">7</sup> For unclean spirits, crying with loud voice, came out of many that were possessed with them: and many taken with palsies, and that were lame, were healed.</span><span class="v44_8_8"> <sup class="v44_8_8">8</sup> And there was great joy in that city.</span></span><span class="para"><span class="v44_8_9"> <sup class="v44_8_9">9</sup> But there was a certain man, called Simon, which beforetime in the same city used sorcery, and bewitched the people of Samaria, giving out that himself was some great one:</span><span class="v44_8_10"> <sup class="v44_8_10">10</sup> to whom they all gave heed, from the least to the greatest, saying, This man is the great power of God.</span><span class="v44_8_11"> <sup class="v44_8_11">11</sup> And to him they had regard, because that of long time he had bewitched them with sorceries.</span><span class="v44_8_12"> <sup class="v44_8_12">12</sup> But when they believed Philip preaching the things concerning the kingdom of God, and the name of Jesus Christ, they were baptized, both men and women.</span><span class="v44_8_13"> <sup class="v44_8_13">13</sup> Then Simon himself believed also: and when he was baptized, he continued with Philip, and wondered, beholding the miracles and signs which were done.</span></span><span class="para"><span class="v44_8_14"> <sup class="v44_8_14">14</sup> Now when the apostles which were at Jerusalem heard that Samaria had received the word of God, they sent unto them Peter and John:</span><span class="v44_8_15"> <sup class="v44_8_15">15</sup> who, when they were come down, prayed for them, that they might receive the Holy Ghost:</span><span class="v44_8_16"> <sup class="v44_8_16">16</sup> (for as yet he was fallen upon none of them: only they were baptized in the name of the Lord Jesus.)</span><span class="v44_8_17"> <sup class="v44_8_17">17</sup> Then laid they their hands on them, and they received the Holy Ghost.</span></span><span class="para"><span class="v44_8_18"> <sup class="v44_8_18">18</sup> And when Simon saw that through laying on of the apostles' hands the Holy Ghost was given, he offered them money,</span><span class="v44_8_19"> <sup class="v44_8_19">19</sup> saying, Give me also this power, that on whomsoever I lay hands, he may receive the Holy Ghost.</span><span class="v44_8_20"> <sup class="v44_8_20">20</sup> But Peter said unto him, Thy money perish with thee, because thou hast thought that the gift of God may be purchased with money.</span><span class="v44_8_21"> <sup class="v44_8_21">21</sup> Thou hast neither part nor lot in this matter: for thy heart is not right in the sight of God.</span><span class="v44_8_22"> <sup class="v44_8_22">22</sup> Repent therefore of this thy wickedness, and pray God, if perhaps the thought of thine heart may be forgiven thee.</span><span class="v44_8_23"> <sup class="v44_8_23">23</sup> For I perceive that thou art in the gall of bitterness, and in the bond of iniquity.</span><span class="v44_8_24"> <sup class="v44_8_24">24</sup> Then answered Simon, and said, Pray ye to the Lord for me, that none of these things which ye have spoken come upon me.</span></span><span class="para"><span class="v44_8_25"> <sup class="v44_8_25">25</sup> And they, when they had testified and preached the word of the Lord, returned to Jerusalem, and preached the gospel in many villages of the Samaritans.</span></span><span class="title-passage"><span>Philip and an Ethiopian</span></span><span class="para"><span class="v44_8_26"> <sup class="v44_8_26">26</sup> And the angel of the Lord spake unto Philip, saying, Arise, and go toward the south unto the way that goeth down from Jerusalem unto Gaza, which is desert.</span><span class="v44_8_27"> <sup class="v44_8_27">27</sup> And he arose and went: and, behold, a man of Ethiopia, an eunuch of great authority under Candace queen of the Ethiopians, who had the charge of all her treasure, and had come to Jerusalem for to worship,</span><span class="v44_8_28"> <sup class="v44_8_28">28</sup> was returning, and sitting in his chariot read Esaias the prophet.</span></span><span class="para"><span class="v44_8_29"> <sup class="v44_8_29">29</sup> Then the Spirit said unto Philip, Go near, and join thyself to this chariot.</span><span class="v44_8_30"> <sup class="v44_8_30">30</sup> And Philip ran thither to him, and heard him read the prophet Esaias, and said, Understandest thou what thou readest?</span><span class="v44_8_31"> <sup class="v44_8_31">31</sup> And he said, How can I, except some man should guide me? And he desired Philip that he would come up and sit with him.</span><span class="v44_8_32"> <sup class="v44_8_32">32</sup> The place of the scripture which he read was this,</span></span>

 <span class="level1">He was led as a sheep to the slaughter;</span>
 <span class="level1">And like a lamb dumb before his shearer,</span>
 <span class="level1">So opened he not his mouth:</span></span><span class="v44_8_33"> <span class="level1"> <sup class="v44_8_33">33</sup> In his humiliation his judgment was taken away:</span>
 <span class="level1">And who shall declare his generation?</span>
 <span class="level1">For his life is taken from the earth.</span>
<span class="para"><span class="v44_8_33"></span><span class="v44_8_34"> <sup class="v44_8_34">34</sup> And the eunuch answered Philip, and said, I pray thee, of whom speaketh the prophet this? of himself, or of some other man?</span></span><span class="para"><span class="v44_8_35"> <sup class="v44_8_35">35</sup> Then Philip opened his mouth, and began at the same scripture, and preached unto him Jesus.</span><span class="v44_8_36"> <sup class="v44_8_36">36</sup> And as they went on their way, they came unto a certain water: and the eunuch said, See, here is water; what doth hinder me to be baptized?</span><span class="v44_8_37"> <sup class="v44_8_37">37</sup> And Philip said, If thou believest with all thine heart, thou mayest. And he answered and said, I believe that Jesus Christ is the Son of God.</span><span class="v44_8_38"> <sup class="v44_8_38">38</sup> And he commanded the chariot to stand still: and they went down both into the water, both Philip and the eunuch; and he baptized him.</span><span class="v44_8_39"> <sup class="v44_8_39">39</sup> And when they were come up out of the water, the Spirit of the Lord caught away Philip, that the eunuch saw him no more: and he went on his way rejoicing.</span><span class="v44_8_40"> <sup class="v44_8_40">40</sup> But Philip was found at Azotus: and passing through he preached in all the cities, till he came to Cæsarea.</span></span>]]></text>
        <book id="eng-KJVA:Acts">
        <chapter id="eng-KJVA:Acts.9">
          <name>Acts 9</name>
        <chapter id="eng-KJVA:Acts.7">
          <name>Acts 7</name>
      <copyright><![CDATA[King James Version 1611 (Authorized Version). Copyright status: UK English with BFBS additions © 2011 British and Foreign Bible Society; Crown Copyright in UK]]></copyright>
var _BAPI=_BAPI||{};
document.write('\x3Cscript src="'+document.location.protocol+'//"\x3E\x3C/script\x3E');}
</script><noscript><img src="" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>]]></fums>
    <fums_js><![CDATA[var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('50534c49b99341.25894942'); }]]></fums_js>
    <fums_noscript><![CDATA[<img src="" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" />]]></fums_noscript>

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 use one or more of these elements to report to the FUMS server as well.

The simplest way to report usage is to include the complete content of the fums element. It contains CDATA-encoded JavaScript and HTML that can be added to any webpage or email message. This is primarily intended to be used if you are accessing the API on the server side and embedding the response data in a page that will be sent to an end user. In this case, just put the contents of the fums element in the page that you send to the client. 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 this FUMS code, it will run automatically. If a single user-facing page contains the results of multiple API requests, you can include all of the HTML and Javascript snippets from each request in the page.

The API responses also contain more fine-grained FUMS information that allow you to create more efficient JavaScript calls to the FUMS server or only include a non-JS tracker image. These are the fums_tid, fums_js_include, fums_js, and fums_noscript elements. These should only be used if you don't want to use the full fums element snippet detailed above.

Here is what each element is for:

  • fums_noscript: An HTML snippet of an <img> tag to include in a page that will log to the FUMS server when it is loaded. This should only be used if none of the following Javascript-based options are used, or else the single display instance will be reported twice.
  • fums_js_include: The location of the Javascript file that contains the _BAPI function definition. You must first include this script URL in the page if you want to call the FUMS Javascript reporting function.
  • fums_js: A snippet of Javascript that you can execute to log the display of this single request.
  • fums_tid: The Transaction ID of this request. If you show the results of multiple API requests to the user at the same time, you can report them all with a single AJAX request by using their Transaction IDs. To do this, first include the FUMS Javascript file in the page, then call _BAPI.t(), passing in the Transaction IDs of the requests. For example: _BAPI.t('504fa05a0edc44.09460032', '505341060e0404.28692206', '504fa18cf13513.96957132');
    Alternatively, you can pass an array of tids to the _BAPI.t() function:
    var tids = ['504fa05a0edc44.09460032', '505341060e0404.28692206']; _BAPI.t(tids);

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 full FUMS snippet:

<!DOCTYPE html>
    <title>Acts 8 (KJV) :: My Site</title>
    <h1>Acts 8 (KJV)</h1>
    <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 ]
        var _BAPI=_BAPI||{};
        document.write('\x3Cscript src="'+document.location.protocol+'//"\x3E\x3C/script\x3E');}
        </script><noscript><img src="" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>

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.