Making use of the ESV Bible Web Service

The publishers of the ESV Bible (the English Standard Version) have kindly provided web application APIs to its text. This page describes one way to access the text so that you can dynamically include ESV readings in your own web pages. There are other ways, of course, some of which I mention below, but this is how I'm doing it.

The main script is written in PHP. It takes a single parameter which is the reference of the passage to look up. So, for example, to lookup Genesis chapter 1 use http://edginet.org/esv/lookup.php?passage=Genesis 1.

The script does its work in three parts: first it gets the XML formatted passage from the ESV's web server via SOAP; next it converts the XML to XHTML with XSLT; and finally it outputs the resulting XHTML to the browser with CSS2 formatting.

These are the scripts that do the work:

• The main script.
• The XSLT script.
• The CSS stylesheet.

1. SOAP

First the passage is retrieved in XML format from the ESV's web server using their SOAP service. SOAP stands for Simple Object Access Protocol and is a standard for exchange of data over the Web.

To make the SOAP calls in PHP I use the nuSOAP library. The script does not do much error-handling yet!

$server = 'http://www.gnpcb.org/esv/share/soap/';
$soapclient = new soapclient($server);
$options = array(
                   'output-format' => 'crossway-xml-1.0',
                   'include-doctype' => 'false',
                   'base-element' => 'paragraph'
                   );
$parameters = array(
                    'key' => $key,
                    'passage' => $passage,
                    'options' => $options
                    );
$xml = $soapclient->call('doPassageQuery',$parameters);

The ESV people also provide a HTTP-GET interface to their web-service, which is probably easier to use. Admittedly, for simple requests SOAP offers little advantage over the GET method, but for potentially more complex interactions that might be implemented in the future SOAP is definitely the way to go.

Note that the above example uses the "doPassageQuery" method to do the passage lookup. If you want to use the more general "doQuery" method then you need to pass the query string (which is called one of q, passage, words or phrase) in the options array. (Thanks to David Moon for alerting me to this difference.) Note that "doQuery" always returns HTML, so the XML options are not relevant. Here is an example,

$server = 'http://www.gnpcb.org/esv/share/soap/';
$soapclient = new soapclient($server);
$options = array(
                 'passage' => $passage,
                 'include-footnotes' => 'false'
                 );
$parameters = array(
                    'key' => $key,
                    'options' => $options
                    );
$html = $soapclient->call('doQuery',$parameters);

For more information see the ESV web service API page.

To use the web services you need to obtain an access key as described on the ESV website. The key 'TEST' can be used for development work: the structure of the resulting XML is correct, but the textual content is garbled.

2. XSLT

Now we have the Bible passage in XML, but to display it in a browser it needs to be converted to HTML, or in this case, XHTML.

To do this I make use of another standard technique called XSLT (XML Stylesheet Language Transformations).

What happens is that a stylesheet, or perhaps more properly a transformation, is applied to the source XML. The transformation is itself written in XML and describes how the various elements of the source XML are to be transformed to produce the desired output. Elements can be omitted, added, reordered and transformed in arbitrary ways. XSLT is a powerful technique. You can view the XSLT script I use to convert the ESV XML into XHTML 1.0 Strict.

Here's how to apply the XSL transformation in PHP. The file esv.xsl is the XSLT. See the main script for more detail.

$arguments = array(
                   '/_xml' => $doctype.$xml,
                   '/_xsl' => implode('',file('esv.xsl'))
                   );

// Indicate the stylesheet to be used
$xsltparams = array( 'style' => 'grey.css' );

$x = xslt_create();
$html = xslt_process(
                     $x,
                     'arg:/_xml',
                     'arg:/_xsl',
                     NULL,
                     $arguments,
                     $xsltparams
                     );
xslt_free($x);

Of course, XSLT is far from the only way of transforming the XML to XHTML. Indeed the ESV people use a PHP script to achieve the same thing, which at first looks more straightforward. The point is that XSLT is designed for the task, so it is easier to do more complex operations (look at how neat the footnote-handling is). In my view XSLT is more flexible, and, since it is standardised, more maintainable.

3. XHTML and CSS2

The final stage is to output the XHTML and format it in the user's browser. The formatting is done entirely with a CSS stylesheet. This is yet another standard technique. The content (the XHTML) is entirely separate from the presentational and formatting aspects which are controlled by the CSS alone. This separation will allow the text to be easily formatted with a variety of styles or skins according to user preference [yet to be implemented].

Additional notes

Test it

Type a passage reference (eg. John 3:16) into the following box and press "Search". The resulting Bible passage will be displayed as if coming from this server and formatted according to my stylesheet.

Anglicising the text

The paper versions of the ESV are available with an anglicised (or anglicized!) text. The online version is available only with the American spellings. For personal use I use a filter to convert the processed XHTML from American to English spelling, which is much more pleasing. However, the terms and conditions of the online text prevent me from providing the altered text online. I can however provide my script so that you can make an anglicised ESV text for yourself if you wish. It's in PHP.

More info

If this is the kind of thing that interests you then you might like to look at my Web Programming pages which have some introductory material and links to all sorts of web-programming technologies. And feel free to contact me.

© Copyright 2003, Ben Edgington. Home