Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

GoodReads.com API enrichment of ALEPH OPAC

Matyas F. Bajger on November 1st, 2016

What is it? JavaScript added to OPAC full document view calls social book network goodreads.com API and adds supplementary information to the document, like book cover, users’ ratings, users’ reviews (using own GoodReads code), and potentially others.

 

Author: Matyáลก F. Bajger, University of Ostrava Library, matyas.bajger@osu.cz, October 2016

Licence: GNU GPL

Working example: http://aleph.osu.cz or directly: http://aleph.osu.cz/F/?func=direct&doc_number=000011280&local_base=OSU01&format=999&con_lng=eng  [[without users’ ratings, which are taking from proper data or other distance services]]

 

How it works? Javascript: OPAC full-view document page is searched for ISBN(s) (both 10 and 13 chars) using ISBN syntax and control checksum. The ISBN(s) is/are sent to CGI script located at OPAC server (due to CORS restrictions for asynchronyous http). The CGI resent the data to goodreads.com and similarly resent the API response to browser. Javascript analyses API JSON response and puts part of its data to special added html elements on the full-view document OPAC page.

 

Requirements: ALEPH ver. 18-22 (tested on version 22). Permission to run CGI scripts on OPAC http server. Browser with XMLHttpRequest and JSON support.

Implementation

For using GoodReads API you need to obtain their developer key used then in each API call. The key can be get here: https://www.goodreads.com/api/keys

 

GoodReads API provides two formats of responses: JSON and XML. Still, the XML version contains just a fragment of data in JSON response, thus JSON is used here – cf.: http:/www.goodreads.com/book/show?format=json&key=licence_key_here&id=409207
http:/www.goodreads.com/book/show?format=xml&key=licence_key_here&id=409207

 

API response of goodreads.com has many various data, still the following have been found as interesting for LIS OPACs and used by this extension:

/GoodreadsResponse/book/image_url    = book cover preview

/GoodreadsResponse/book/description  = book description / annotation

/GoodreadsResponse/book/average_rating  = users’ rating (from 1 to 5]

/GoodreadsResponse/book/url  = backling to portal goodreads.com

/GoodreadsResponse/book/reviews_widget  = html code – widget with user’s rating

 

 

1. Get and save scripts + images

 

  • Get / download the external javascript goodreads.js, bash cgi script goodreads.cgi and images used by this script: goodreads_logo.gif and rating_plus.gif + rating_minus.gif [=these are filled or empty stars for graphical presentation of the rating]. The scripts and images can be get as gzip pack at http://aleph.osu.cz/goodreads/pack/goodreads_aleph.tar.gz
  • Save the Javascript goodreads.js and images to directory $httpd_root/htdocs/goodreads  If you choose another dir, you must change paths in instructions below and links to images in goodreads.js
  • Save the CGI script goodreads.cgi to directory with Apache permission to run CGI scripts – usually $httpd_root/cgi-bin
  • Modify the CGI script goodreads.cgi – add your developer key to the 2nd line:
    goodreadsAPIkey='xxxxx’

 

2. Modify OPAC www templates

In the www_f_lng (like www_f_eng) directory, you need to modify files for full document view, part *-tail. These files/html templates should be: full-set-tail, direct-tail, myshelf-full-tail

Put the following code to that place in the page, where you want to add extensions got from Goodreads API:

<div id="good_reads_cover" style="display: none;"></div>
<div id="good_reads_description" style="display: none;"></div>
<div id="good_reads_rating" style="display: none;"></div>
<div id="good_reads_reviews" style="display: none;"></div>
<script type="text/javascript" src="/goodreads/goodreads.js"></script>
<script type="text/javascript">
   goodReads.ask();
</script>

 

Description:  Div elements are filled with data from API response:

  • good_reads_cover = book cover with Goodreads icon and anchor to the book at www Gooreads
  • good_reads_description = book annotation. Text in “simple html”, i.e. with <br> <em> <strong> etc. tags is inserted in this. You should modify the style of this div according to your OPAC design (add border etc.)
  • good_reads_rating = API returns rating 1-5. The script generates 5 stars – filled or empty according to the rating value, with “title” attribute (showing on mouse over in most browsers) with more information about rating.
  • good_reads_reviews = full html code = widget with users’ reviews, buttons to add new review etc. This widget has proper CSS file, which can be modified according to own OPAC design.
The first <script… loads external javascript file, which manages the whole process.
The second <script… runs function calling API and whole process.

 

Miscellanea

The ISBNs are taken from whole html page using (document.body.textContent || document.body.innerText) object. If you have added more information to default ALEPH full-view template, were further ISBNs may occure (like similar books), you should change the method of getting the ISBN in goodreads.js, like marking the correct ISBN with id attribute and getting the identifier from this element.