GoodReads.com API enrichment of ALEPH OPAC
What is it?
Author: Matyáš F. Bajger, University of Ostrava Library, firstname.lastname@example.org, 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]]
Requirements: ALEPH ver. 18-22 (tested on version 22). Permission to run CGI scripts on OPAC http server. Browser with XMLHttpRequest and JSON support.
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
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
- 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:
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:
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 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.