API.bible Logo

Documentation Navigation

Fair Use

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?

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.

Request

curl -h "api-key: <API-TOKEN>" https://api.scripture.api.bible/v1/bibles/a6aee10bb058511c-02/chapters/ACT.7

Response

{
"data": {
"id": "ACT.7",
"bibleId": "a6aee10bb058511c-02",
"number": "7",
"bookId": "ACT",
"reference": "Acts 7",
"copyright": "King James Version 1611, spelling, punctuation and text formatting modernized by ABS in 1962; typesetting © 2010 American Bible Society.",
"content": "<p class=\"s1\">Stephen's Defense</p><p class=\"p\"><span data-number=\"1\" class=\"v\">1</span>Then said the high priest, Are these things so? <span data-number=\"2\" class=\"v\">2</span> And he said,</p><p class=\"p\">Men, brethren, and fathers, hearken; The God of glory appeared unto our father Abraham, when he was in Mesopota´mi-a, before he dwelt in Haran, <span data-number=\"3\" class=\"v\">3</span>and said unto him, Get thee out of thy country, and from thy kindred, and come into the land which I shall show thee. <span data-number=\"4\" class=\"v\">4</span> Then came he out of the land of the Chalde´ans, and dwelt in Haran: and from thence, when his father was dead, he removed him into this land, wherein ye now dwell. <span data-number=\"5\" class=\"v\">5</span> And he gave him none inheritance in it, no, not <span class=\"add\">so much as</span> to set his foot on: yet he promised that he would give it to him for a possession, and to his seed after him, when <span class=\"add\">as yet</span> he had no child. <span data-number=\"6\" class=\"v\">6</span> And God spake on this wise, That his seed should sojourn in a strange land; and that they should bring them into bondage, and entreat <span class=\"add\">them</span> evil four hundred years. <span data-number=\"7\" class=\"v\">7</span>And the nation to whom they shall be in bondage will I judge, said God: and after that shall they come forth, and serve me in this place. <span data-number=\"8\" class=\"v\">8</span> And he gave him the covenant of circumcision: and so <span class=\"add\">Abraham</span> begat Isaac, and circumcised him the eighth day; and Isaac <span class=\"add\">begat</span> Jacob; and Jacob <span class=\"add\">begat</span> the twelve patriarchs.</p><p class=\"p\"><span data-number=\"9\" class=\"v\">9</span> And the patriarchs, moved with envy, sold Joseph into Egypt: but God was with him, <span data-number=\"10\" class=\"v\">10</span> and delivered him out of all his afflictions, and gave him favor and wisdom in the sight of Pharaoh king of Egypt; and he made him governor over Egypt and all his house. <span data-number=\"11\" class=\"v\">11</span> Now there came a dearth over all the land of Egypt and Canaan, and great affliction: and our fathers found no sustenance. <span data-number=\"12\" class=\"v\">12</span> But when Jacob heard that there was corn in Egypt, he sent out our fathers first. <span data-number=\"13\" class=\"v\">13</span> And at the second <span class=\"add\">time</span> Joseph was made known to his brethren; and Joseph's kindred was made known unto Pharaoh. <span data-number=\"14\" class=\"v\">14</span> Then sent Joseph, and called his father Jacob to <span class=\"add\">him</span>, and all his kindred, threescore and fifteen souls. <span data-number=\"15\" class=\"v\">15</span> So Jacob went down into Egypt, and died, he, and our fathers, <span data-number=\"16\" class=\"v\">16</span> and were carried over into Shechem, and laid in the sepulchre that Abraham bought for a sum of money of the sons of Hamor, <span class=\"add\">the father</span> of Shechem.</p><p class=\"p\"><span data-number=\"17\" class=\"v\">17</span> But when the time of the promise drew nigh, which God had sworn to Abraham, the people grew and multiplied in Egypt, <span data-number=\"18\" class=\"v\">18</span>till another king arose, which knew not Joseph. <span data-number=\"19\" class=\"v\">19</span> The same dealt subtilely with our kindred, and evil entreated our fathers, so that they cast out their young children, to the end they might not live. <span data-number=\"20\" class=\"v\">20</span> In which time Moses was born, and was exceeding fair, and nourished up in his father's house three months: <span data-number=\"21\" class=\"v\">21</span> and when he was cast out, Pharaoh's daughter took him up, and nourished him for her own son. <span data-number=\"22\" class=\"v\">22</span>And Moses was learned in all the wisdom of the Egyptians, and was mighty in words and in deeds.</p><p class=\"p\"><span data-number=\"23\" class=\"v\">23</span> And when he was full forty years old, it came into his heart to visit his brethren the children of Israel. <span data-number=\"24\" class=\"v\">24</span>And seeing one <span class=\"add\">of them</span> suffer wrong, he defended <span class=\"add\">him</span>, and avenged him that was oppressed, and smote the Egyptian: <span data-number=\"25\" class=\"v\">25</span>for he supposed his brethren would have understood how that God by his hand would deliver them; but they understood not. <span data-number=\"26\" class=\"v\">26</span>And the next day he showed himself unto them as they strove, and would have set them at one again, saying, Sirs, ye are brethren; why do ye wrong one to another? <span data-number=\"27\" class=\"v\">27</span>But he that did his neighbor wrong thrust him away, saying, Who made thee a ruler and a judge over us? <span data-number=\"28\" class=\"v\">28</span>Wilt thou kill me, as thou didst the Egyptian yesterday? <span data-number=\"29\" class=\"v\">29</span> Then fled Moses at this saying, and was a stranger in the land of Mid´i-an, where he begat two sons.</p><p class=\"p\"><span data-number=\"30\" class=\"v\">30</span> And when forty years were expired, there appeared to him in the wilderness of mount Si´nai an angel of the Lord in a flame of fire in a bush. <span data-number=\"31\" class=\"v\">31</span>When Moses saw <span class=\"add\">it</span>, he wondered at the sight: and as he drew near to behold <span class=\"add\">it</span>, the voice of the Lord came unto him, <span data-number=\"32\" class=\"v\">32</span><span class=\"add\">saying</span>, I <span class=\"add\">am</span> the God of thy fathers, the God of Abraham and the God of Isaac, and the God of Jacob. Then Moses trembled, and durst not behold. <span data-number=\"33\" class=\"v\">33</span>Then said the Lord to him, Put off thy shoes from thy feet: for the place where thou standest is holy ground. <span data-number=\"34\" class=\"v\">34</span>I have seen, I have seen the affliction of my people which is in Egypt, and I have heard their groaning, and am come down to deliver them. And now come, I will send thee into Egypt.</p><p class=\"p\"><span data-number=\"35\" class=\"v\">35</span>This Moses whom they refused, saying, Who made thee a ruler and a judge? the same did God send <span class=\"add\">to be</span> a ruler and a deliverer by the hand of the angel which appeared to him in the bush. <span data-number=\"36\" class=\"v\">36</span> He brought them out, after that he had showed wonders and signs in the land of Egypt, and in the Red sea, and in the wilderness forty years. <span data-number=\"37\" class=\"v\">37</span> This is that Moses, which said unto the children of Israel, A Prophet shall the Lord your God raise up unto you of your brethren, like unto me; him shall ye hear. <span data-number=\"38\" class=\"v\">38</span> This is he, that was in the church in the wilderness with the angel which spake to him in the mount Si´nai, and <span class=\"add\">with</span> our fathers: who received the lively oracles to give unto us: <span data-number=\"39\" class=\"v\">39</span>to whom our fathers would not obey, but thrust <span class=\"add\">him</span> from them, and in their hearts turned back again into Egypt, <span data-number=\"40\" class=\"v\">40</span> saying unto Aaron, Make us gods to go before us: for <span class=\"add\">as for</span> this Moses, which brought us out of the land of Egypt, we wot not what is become of him. <span data-number=\"41\" class=\"v\">41</span> And they made a calf in those days, and offered sacrifice unto the idol, and rejoiced in the works of their own hands. <span data-number=\"42\" class=\"v\">42</span> Then God turned, and gave them up to worship the host of heaven; as it is written in the book of the prophets,</p><p class=\"q\">O ye house of Israel,</p><p class=\"q\">have ye offered to me slain beasts and sacrifices</p><p class=\"q\"><span class=\"add\">by the space of</span> forty years in the wilderness?</p><p class=\"q\"><span data-number=\"43\" class=\"v\">43</span>Yea, ye took up the tabernacle of Moloch,</p><p class=\"q\">and the star of your god Remphan,</p><p class=\"q\">figures which ye made to worship them:</p><p class=\"q\">and I will carry you away beyond Babylon.</p><p class=\"p\"><span data-number=\"44\" class=\"v\">44</span> Our fathers had the tabernacle of witness in the wilderness, as he had appointed, speaking unto Moses, that he should make it according to the fashion that he had seen. <span data-number=\"45\" class=\"v\">45</span> Which also our fathers that came after brought in with Joshua into the possession of the Gentiles, whom God drave out before the face of our fathers, unto the days of David; <span data-number=\"46\" class=\"v\">46</span> who found favor before God, and desired to find a tabernacle for the God of Jacob. <span data-number=\"47\" class=\"v\">47</span> But Solomon built him a house. <span data-number=\"48\" class=\"v\">48</span>Howbeit the Most High dwelleth not in temples made with hands; as saith the prophet,</p><p class=\"q\"><span data-number=\"49\" class=\"v\">49</span> Heaven <span class=\"add\">is</span> my throne,</p><p class=\"q\">and earth <span class=\"add\">is</span> my footstool:</p><p class=\"q\">what house will ye build me? saith the Lord:</p><p class=\"q\">or what <span class=\"add\">is</span> the place of my rest?</p><p class=\"q\"><span data-number=\"50\" class=\"v\">50</span>Hath not my hand made all these things?</p><p class=\"p\"><span data-number=\"51\" class=\"v\">51</span> Ye stiffnecked and uncircumcised in heart and ears, ye do always resist the Holy Ghost: as your fathers <span class=\"add\">did</span>, so <span class=\"add\">do</span> ye. <span data-number=\"52\" class=\"v\">52</span>Which of the prophets have not your fathers persecuted? and they have slain them which showed before of the coming of the Just One; of whom ye have been now the betrayers and murderers: <span data-number=\"53\" class=\"v\">53</span>who have received the law by the disposition of angels, and have not kept <span class=\"add\">it</span>.</p><p class=\"s1\">The Stoning of Stephen</p><p class=\"p\"><span data-number=\"54\" class=\"v\">54</span>When they heard these things, they were cut to the heart, and they gnashed on him with <span class=\"add\">their</span> teeth. <span data-number=\"55\" class=\"v\">55</span>But he, being full of the Holy Ghost, looked up steadfastly into heaven, and saw the glory of God, and Jesus standing on the right hand of God, <span data-number=\"56\" class=\"v\">56</span>and said, Behold, I see the heavens opened, and the Son of man standing on the right hand of God. <span data-number=\"57\" class=\"v\">57</span>Then they cried out with a loud voice, and stopped their ears, and ran upon him with one accord, <span data-number=\"58\" class=\"v\">58</span>and cast <span class=\"add\">him</span> out of the city, and stoned <span class=\"add\">him</span>: and the witnesses laid down their clothes at a young man's feet, whose name was Saul. <span data-number=\"59\" class=\"v\">59</span>And they stoned Stephen, calling upon <span class=\"add\">God</span>, and saying, Lord Jesus, receive my spirit. <span data-number=\"60\" class=\"v\">60</span>And he kneeled down, and cried with a loud voice, Lord, lay not this sin to their charge. And when he had said this, he fell asleep.</p>",
"next": {
"id": "ACT.8",
"number": "8",
"bookId": "ACT"
},
"previous": {
"id": "ACT.6",
"number": "6",
"bookId": "ACT"
}
},
"meta": {
"fums": "<script>\nvar _BAPI=_BAPI||{};\nif(typeof(_BAPI.t)==='undefined'){\ndocument.write('\\x3Cscript src=\"'+document.location.protocol+'//cdn.scripture.api.bible/fums/fumsv2.min.js\"\\x3E\\x3C/script\\x3E');}\ndocument.write(\"\\x3Cscript\\x3E_BAPI.t('cc68d038-6a46-4949-807b-5c817aaa0329');\\x3C/script\\x3E\");\n</script><noscript><img src=\"https://d3a2okcloueqyx.cloudfront.net/nf1?t='cc68d038-6a46-4949-807b-5c817aaa0329'\" height=\"1\" width=\"1\" border=\"0\" alt=\"\" style=\"height: 0; width: 0;\" /></noscript>",
"fumsId": "cc68d038-6a46-4949-807b-5c817aaa0329",
"fumsJsInclude": "cdn.scripture.api.bible/fums/fumsv2.min.js",
"fumsJs": "var _BAPI=_BAPI||{};if(typeof(_BAPI.t)!='undefined'){ _BAPI.t('cc68d038-6a46-4949-807b-5c817aaa0329'); }",
"fumsNoScript": "<img src=\"https://d3btgtzu3ctdwx.cloudfront.net/nf1?t=cc68d038-6a46-4949-807b-5c817aaa0329\" height=\"1\" width=\"1\" border=\"0\" alt=\"\" style=\"height: 0; width: 0;\" />"
}
}

In the example above, note the section the begins with "meta". 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>
<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+'//cdn.scripture.api.bible/fums/fumsv2.min.js"\x3E\x3C/script\x3E');}
document.write("\x3Cscript\x3E_BAPI.t('' + unique + '');\x3C/script\x3E");
</script><noscript><img src="https://d3a2okcloueqyx.cloudfront.net/nf1?t=' + unique + '" height="1" width="1" border="0" alt="" style="height: 0; width: 0;" /></noscript>
</body>
</html>

The script tag 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.