LDSTechForumProjects

Gospel Library Web Service

Mobile Gospel Library Project Index edit

The Gospel Library Web Service is a service that can be used by official LDS Church applications to query and retrieve content from the Gospel Library. This article will provide technical help information about the web service.

Service URL

The URL for this service can be found at https://lds.org/ws/mobilesearch/v1.0/search.xqy

Reference

To use one of the tags listed below, add a "?" (question mark) to the end of the URL followed by the tag. To have multiple tags, simply put "&" (the ampersand character) between each one with no whitespace. See http://en.wikipedia.org/wiki/Query_string for more information on how to formulate a query string.

If an invalid value is provided for a parameter, the service will use the default value for that parameter. It will not rewrite the query string, however.

If duplicate parameters are provided, the service will take the first instance and ignore any subsequent instances.

Name Description Valid values Example Usage
help Optional. This help file.

Note: This parameter overrides any other parameter.

[true | false] help=true
stop-words Optional. Default is retain. Used to specify whether stop words (or common words) should be retained or removed.

Note: If you combine phrase=true and stop-words=remove, the phrase will have any stop words contained inside it removed. For that reason, this combination of parameters should be used with caution.

Stop words used in the LDS Scriptures Service:

a, am, an, and, are, as, at, be, been, but, by, for, from, how, i, if, in, is, it, nor, not, of, on, or, out, that, the, these, this, those, to, too, was, were, what, when, where, who, whose, why, ye, yea, you

For a list of the stop words used in this service in an XML format, see LDS Scriptures Service Stop Words

[remove | retain] terms=word+of+wisdom&stop-words=remove
terms Required. A string of characters, numbers and whitespace, with whitespace replaced by the plus (+) sign. If this parameter is not specified, a response element of type=empty will be returned. [a-zA-Z0-9+] terms=word+of+wisdom
testament Optional. Default is all. Used to designate a single testament, a combination of testaments, or all testaments. Invalid values are ignored.
  • ot = Old Testament
  • nt = New Testament
  • bofm = The Book of Mormon
  • dc = Doctrine and Covenants
  • pgp = The Pearl of Great Price
  • jst = The Joseph Smith Translation (of the Bible)
[all | ot | nt | bofm | dc | pgp | jst] terms=word+of+wisdom&testament=ot,bofm,jst
element Optional. Default is verse. Used to specify whether chapters or verses will be used for relevance ranking and snippeting.

Note: element=chapter is not implemented.

[verse | chapter] terms=word+of+wisdom&element=verse
page Optional. Default is 1. Used to specify which page of results to return. An integer greater than or equal to 1 and less than or equal to the maximum number of pages. terms=word+of+wisdom&page=3
results Optional. Default is 10; maximum is 100. Used to specify the number of results to return per page. An integer greater than or equal to 1 and less than or equal to 100. terms=word+of+wisdom&results=25
highlight Optional. Default is true. Used to specify whether matching terms should be highlighted. [true | false] terms=word+of+wisdom&highlight=false
format Optional. Default is xml. Used to specify whether results should be returned as XML or JSON. [xml | json] terms=word+of+wisdom&format=json


include-uri Optional. Default is false. Used to specify whether the URI attribute should be included. The URI attribute can be used to jump directly to a verse or chapter element when directly querying XML. This parameter is meaningful only to applications that have a local copy of the official LDS Scriptures in ldsXML. [true | false] terms=word+of+wisdom&include-uri=true
case-sensitive Optional. Default is false. Used to specify whether searches are to be case-sensitive. [true | false] terms=word+of+wisdom&case-sensitive=true
snippet Optional. Default is verse. Used to specify whether the search result text should be the entire verse or an extract of words surrounding the matching terms. [verse | extract] terms=word+of+wisdom&snippet=extract
phrase Optional. Default is false. Used to specify whether the terms should be treated as a contiguous phrase or as individual terms.

Note: If you combine phrase=true and stop-words=remove, the phrase will have any stop words contained inside it removed. For that reason, this combination of parameters should be used with caution.

[true | false] terms=word+of+wisdom&phrase=true

Examples

Below are examples of queries. Click on a query to see the results returned by the service.

  1. Show all verses that contain the exact phrase "SAVIOR OF".
    https://lds.org/ws/mobilesearch/v1.0/search.xqy?terms=SAVIOR+OF&phrase=true
  2. Show all verses that contain the exact phrase "SAVIOR OF" in JSON format.
    https://lds.org/ws/mobilesearch/v1.0/search.xqy?terms=SAVIOR+OF&phrase=true&format=json
  3. Show all verses in the Doctrine and Covenants that contain any of the words in "Word of Wisdom," but make it case-sensitive and don't use highlights in the results.
    https://lds.org/ws/mobilesearch/v1.0/search.xqy?terms=word+of+wisdom&testament=dc&case-sensitive=true&highlight=false

Explanation of XML format

The following is the XML that is returned when executing the first query above. An explanation of each of the elements and attributes can be found below it.

<response>
     <total>3</total>
     <r>
          <v a="dc" b="D&C" c="1" v="20">D&C 1:20</v>
          <s>But that every man might speak in the name of God the Lord, even the <h>Savior of</h> the world;</s>
     </r>
     <r>
          <v a="1-ne" b="1 Nephi" c="10" v="4">1 Nephi 10:4</v>
           <s>Yea, even six hundred years from the time that my father left 
                Jerusalem, a prophet would the Lord God raise up among the Jews—even
                a Messiah, or, in other words, a <h>Savior of</h> the world.</s>
     </r>
     <r>
          <v a="dc" b="D&C" c="42" v="1">D&C 42:1</v>
          <s>Hearken, O ye elders of my church, who have assembled yourselves
                together in my name, even Jesus Christ the Son of the living God,
                the <h>Savior of</h> the world; inasmuch as ye believe on my
                name and keep my commandments.</s>
     </r>
     <qtext>"SAVIOR OF"</qtext>
     <t>PT0.011849S</t>
</response>

Elements and attributes

Value Type Description
response element The root element of the HTTP response.
total element The total number of results.
r (result) element A result element containing a verse element and a snippet element. Together, these elements can be used to present a title, a link to the verse, and a snippet of text showing where the matching term or terms appear.
v (verse) element A verse element containing attributes that can be used to locate a reference. The text node of this element is a full scripture citation.
s (snippet) element The verse text. If highlight=false, this will be the plain text of the verse.
a (book abbreviation) attribute An abbreviation for the book. A list of valid book abbreviations can be found in the documentation for ldsXML.
b (book) attribute The proper name of the book.
c (chapter) attribute The chapter in the book.
v (verse) attribute The verse in the chapter.
u (URI) attribute The canonical URI of this verse. This attribute appears only if include-uri=true.
h (hit) element This element encloses the term or terms matching the search term(s).
qtext (query text) element The original query text. If phrase=true, the original term(s) will be enclosed in double-quote marks.
t (time) element The total amount of time (in seconds/microseconds) it took to process the query. This does not include network or rendering time. In the example above, the query took 0.011849 seconds, or 11.849 milliseconds, or 11,849 microseconds.
This page was last modified on 31 March 2011, at 16:54.

Note: Content found in this wiki may not always reflect official Church information. See Terms of Use.