A Python Interface for api.Biblia.com

Last week Logos announced a public API for their new website, Biblia.com, at BibleTech. Of course, i want to wave the flag for my employer. But i’m also interested as somebody who’s dabbled in Bible web services in the past, most notably the excellent ESV Bible web service (many aspects of which are mirrored in the Biblia API: some previous posts around this can be found here at Blogos in the Web Services category). Dabblers like me often face a perennial problem: the translations people most want to read are typically not the most accessible via API, or have various other limitations.

So i’m happy with the other announcement from BibleTech last week: Logos is making the Lexham English Bible available under very generous terms (details here). The LEB is in the family of “essentially literal” translations, which makes it a good choice for tasks where the precise wording matters. And the LEB is available through the API (unlike most other versions you’re likely to want, at least until we resolve some other licensing issues).

I don’t want to do a review of the entire API here (and it will probably continue to evolve). But here are a couple of things about it that excite me:

  • The most obvious one is the ability to retrieve Bible text given a reference (the content service). Of the currently available Bible versions, the LEB is the one that interests me the most here (i hope we’ll have others in the future).
  • Another exciting aspect for me is the tag service. You provide text which may include Bible references: the service identifies any references embedded in it, and then inserts hyperlinks for them to enrich the text. So this is like RefTagger on demand (not just embedded in your website template). You can also supply a URL and tag the text that’s retrieved from it. One caveat with this latter functionality: if you want to run this on HTML, you should plan to do some pre-processing first, rather than treating it all as one big string. Otherwise random things (like “XHTML 1.0” in a DOCTYPE declaration) wind up getting tagged in strange ways (like <a href="http://ref.ly/Mal1">ML 1.0</a>).

I’ve just started working through the Biblia API today, but since i’m a Pythonista, developing a Python interface seemed like the way to go. This is still very much a work in progress, but you can download the code from this zip file and give it a whirl. Caveats abound:

  • I’ve only implemented three of the services so far: content() (retrieves Bible content for a reference), find() (lists available Bibles and metadata), and tag() (finds references in  text and enhances it with hyperlinks). And even with these three services, i haven’t supported all the parameters (maybe i will, maybe i won’t).
  • This is my first stab at creating a Python interface to an API, so there may be many stylistic shortcomings.
  • Testing has also gotten very little attention, and bugs doubtless remain.

If you’re interested and want to play along, let me know: we can probably set up a Google group or something for those who want to improve this code further.

Bookmarklets Redux

Time spent on the web can be oh-so tedious if you’re constantly cutting things from one page and pasting them elsewhere just to get to another, related page. Someday Linked Data may make this all better, but until then, we all get by with helpful tricks.

Bookmarklets are one essential weapon in the arsenal of the web-info-warrior. Usually they’re little JavaScript programs stored as a bookmark in Firefox, providing one-click access to some simple functionality like looking things up elsewhere, resizing your window, etc. I’ve blogged previously about bookmarklets to find local library sources for a book on an Amazon page (or PaperBackSwap).

I dusted off my bookmarklet skills this past week and came up with some nifty tools that i wanted to share.

First off, imagine you’re looking at a website with Bible references whose benighted author somehow failed to include RefTagger. So rather than a nice pop-up with the text of the reference, or even a helpful link to that text on some Bible site, you’re just looking at a inanimate, unlinked string: boo. The Bible Reference Bookmarklet to the rescue! Simply select the text of the reference, click the bookmarklet, and you’ll be whisked off to that reference at Bible.Logos.com. If you haven’t selected any text first, you get a dialogue box asking for it.

To get this goodie in Firefox, first make sure the Bookmarks Toolbar is showing (View > Toolsbars > Bookmarks Toolbar must be checked). I’d love to give you a link to just drag onto the toolbar, but i don’t seem to be able to get the code past WordPress. So go to Bookmarks > Organize Bookmarks, and select Organize > New Bookmark. Give it a useful name like “Bible Reference Lookup”, and paste the code below in Location field.

javascript:(function(){%20function%20getSearchString%20(promptString)%20{%20s%20=%20null;
if%20(document.selection%20&&%20document.selection.createRange)%20{%20s%20=document.selection.createRange().text;%20}%20
else%20if%20(document.getSelection)%20{%20s=%20document.getSelection();%20}%20
if%20(!%20(s%20&&%20s.length))%20{%20s%20=prompt(promptString,'');%20}
%20return%20s;%20}%20searchString%20=%20getSearchString('Bible%20Reference%20to%20look%20up%20:');%20
if%20(searchString%20!=%20null)%20{%20if(searchString.length)%20{%20location%20='http://bible.logos.com/#ref='+escape(searchString);%20}%20
else%20{%20location%20='http://bible.logos.com/';%20}%20}%20%20})();

After you’ve clicked ok, you should see it on your toolbar.

You can do similar tricks for a wide variety of strings that you just want to look up elsewhere (i discovered one here while writing this post that lets you look up articles on Wikipedia). This isn’t fundamentally different from copying the string into a search box: but sometimes it’s more convenient.

Descending into more esoteric purposes (to give you ideas for your own bookmarklets): as part of an earlier post on Tools for Personal Knowledge Management, i mentioned my use of TiddlyWiki for quick organization of hyperlinked notes. Like other wiki software, TiddlyWiki has its own link syntax, that looks like

[[Link text | URL]]

When linking to lots of other web pages, i was getting tired of copying the URL, pasting that in, then typing the square brackets, link text, vertical bar, and more square brackets, all in the right format. Wouldn’t it be more convenient to just construct this expression from the title of the page and its URL, rather than having to type it myself? YES! and the TiddlyWiki Page Link bookmarklet does just that, putting the result in a little pop-up window where a triple-click selects the whole thing, ready to copy and paste into your tiddlywiki (and tailor as desired: the title isn’t always what you want, but it’s often easier to edit and throw things out rather than type afresh). This one you can just drag to your bookmarks toolbar and use right away.

TiddlyWiki Page Link

Also, i’ve switched to a much better library lookup bookmarklet (and a service to help you create one for your local library) from WorldCat. Among other things, it generates the list of all the different ISBNs that might exist for a title (which can be very long indeed), and when there are many, it provides links for alternate searches in case the first group comes up empty handed.

Some other cool bookmarklets in my collection include:

  • CiteULike Popup Post and kin to make it easy to add (certain kinds of) articles to your reading list management. Adds more value for sources whose structure it understands.
  • Show del.icio.us citations of the current URL (you can find it there)
  • Resize your browser window to 1024 x 768 (if you want to see how a page will look on a smaller monitor or projector): the bookmarklet follows, just drag to your toolbar. 1024 x 768
  • A CSS validator for the current page: see Pete Freitag’s page.

Hat tips:

A Review of Oxford Biblical Studies Online

A number of bibliobloggers have been helping Oxford University Press advertise their new on-line website, Oxford Biblical Studies Online, with a free-access pass good through the end of May (I learned of it through my colleague Mike Heiser’s blog). Since i wasn’t one of them 🙂 i can give an honest evaluation of the time i spent perusing their site. 

Their site offers an integrated tool for accessing

  • Six different Bibles, along with concordances and the Oxford Bible Commentary
  • Reference tools that span nine different sources (The Oxford Companion to the Bible, Oxford Bible Atlas, Oxford Encyclopedia of Archaeology in the Near East, etc.)
  • A collection of about 1000 images and maps.

Whether this is helpful to you will be strongly determined by whether you value Oxford’s resources, of course: this is a walled (publisher) garden in that respect. But in my opinion (and those of real scholars as well) there’s a lot of very good material here. They provide an integrated search feature so you can search by keyword across all the reference works, Bible texts, and image resources. You can also limit that search by some general domains like Archaeology, Geography, Material Culture, etc.: that’s a nice way to make the search results a little more manageable in size. 

There’s also a timeline feature, with links to the reference works (like Oxford History of the Biblical World and Companion to the Bible). I found that an interesting way to navigate to relevant information: you can find an item in the timeline (“Manasseh is king of Judah”) and then follow a link to an article on Manasseh.This kind of interface, where you can get to new information without first having to know exactly what you’re looking for, is important for those who aren’t already specialists in the domain of Biblical studies. 

One very helpful feature is that dictionary-type articles have some number of terms hyperlinked: Bible references, of course, but also maps and other articles. So the article on Manasseh links to articles on Chronicles, Deuteronomic History, Ephraim (for the “other” Manasseh: the article combines both), and others. These links are also displayed in a sidebar, not just embedded in the text. This feature is limited somewhat, though, by the fact that the links are only within the current reference. What would make this feature really useful would be to link across their collection, so you could also easily get to e.g. the Bible Dictionary article on Ephraim. Of course, you can do that by going back to the search interface, but that’s some added friction. Also, it would appear that at least some of the links were automatically generated: the prose about Manasseh (son of Joseph the patriarch) links to “Joseph (Husband of Mary)”. 

I found a few things i didn’t like as well. While the “unbundled” content of the reference tools is available, in some cases (for example, the Companion to the Bible) i couldn’t figure out a way to actually read the books as books: i could only get to them as disembodied search results. I suppose that’s all right for strict reference purposes, since search is probably the normal way you’d access them. But since some other volumes (like the Illustrated History of the Bible) can be read sequentially, i don’t quite understand why this isn’t possible for all of them. Another mild annoyance: while they helpfully link Bible references to their text, they only put the chapter and verse in the hyperlink, like this:

Amos 9: 9        

In addition to looking a little weird, it also makes for a smaller (and therefore harder to hit) mouse target. I can understand doing this in a list of references where the book name isn’t repeated: but where the book is adjacent in the text, i don’t see the rationale. I also noticed that some features of the site (like Look It Up) didn’t seem to work quite right with Google Chrome.

These are pretty mild complaints, however. Overall, i’d say there’s a lot of very valuable information available here. The annual subscription price of $295 would seem to best fit serious professional users, however. I’d encourage you to take advantage of the free trial period and investigate it for yourself. 

[This seems like as good an opportunity as any to point out that i followed the good example of my colleague Rick Brannan and created a Disclosures page, to avoid any potential confusion about my financial relationship to the things i write about. In this context, full disclosure: i work for a company that is partially in competition with Oxford’s site. ]