WorldCat Identities Widget

Background

At the OCLC Mashathon held in May 2009 in Amsterdam, a group of developers discussed ways in which WorldCat APIs (also known as OCLC Grid Services) can be used to extend access from library catalog interfaces. We quickly focused on the use of the WorldCat Identities API to find related authors, books by and about, subjects, and other facets of information associated with an author and a work.

The group was also interested in developing an application that would return data that would be easily incorporated into a library catalog user interface. We found that just a portion of the XML returned for an Identities record (just the works by an author, just the subjects associated with the author) would typically be needed, and that some other presentation of the XML (HTML formatted for the UI, or JSON for rendering by local JavaScript) would be important.

So the group set out to build a working prototype of a "widget" application; one that could be called with a few values known to the local catalog system and that would return an easily-incorporated bit of additional information.

A quick way to find an Identities record is to send a request that includes a last name and an OCLC number of a record with which they are associated. Library catalogs can easily generate last names, but not all will have an OCLC number handy for a record for that person in WorldCat. Some of the participants in the group had PPNs instead of OCLC numbers. So we began by building a widget that, given a PPN, calls a web service from that can return a related OCLC number.

Next we extended the widget so that, given a PPN and a last name, it would get the related OCLC number and formulate a request to call the WorldCat Identities API and return a matching record's XML, if found. Since Identities records can include several separate "facets" of information separate XML elements, we added a widget URL parameter so that a particular facet could be extracted and returned.

We then added an extension to the widget so that it could accept an OCLC number directly, for those with a number handy. And we further extended it to work with systems that had neither a PPN or OCLC number. If given a title string along with the last name, the widget formulates a WorldCat Search API URL (including a key provided by the widget implementer) to issue an author/title search in WorldCat, and if there are matches it extracts the OCLC identifier of the first matching work to use in an Identities API request.

Prototype Widget

The prototype built during the Mashathon is available for evaluation. This implementation is not intended for high-level use in a production environment.

Sample links for the prototype widget:

• with a ppn and last name, get associatedNames in xml
• with a ppn and last name, get associatedNames in xml, use "xml" as the node name for response
• with a ppn and last name, get associatedNames in json using "ws_result" as the callback function name
• with a ppn and last name, get associatedNames in javascript variable assignment
• with an oclc number and last name, get XML subject headings
• with a title and last name, get citations of works about in XML and apply a remote XSLT stylesheet

Download Code

Code is available from the Developer Network Subversion Repository

Installation Notes

To use the following PHP code, install in a directory on your PHP server. Also download and install the xml2json PHP application, and modify the "require_once" statement in the PHP code below as needed for your installation. As written, the code assumes that xml2json.php is installed in the same directory as the prototype PHP code, with a subdirectory named "json" that includes the xml2json JSON.php code and license.

The PHP code provides access to API keys on the PHP server is through a scheme that is unique to this installation. We'd expect an implementation to replace the key lookup implementation in this code with a similar method in use in the implementer's environment.

Widget URL Parameters

• ppn -- A PPN number to identify a bibliographic record (required if title or oclc not provided)
• oclc -- An OCLC number to identify a bibliographic record (required if ppn or title not provided)
• last -- An author's family name (required)
• facet -- A WorldCat Identities facet. If not supplied, the complete Identities record is returned. Parameter values include:
  • 
    about -- citations of works about the identity
  • audLevel -- OCLC audience level calculations for works by the identity
  • authorityInfo -- name authority file entries for the identity
  • biogSHs -- biographical subject headings for the identity
  • by -- citations of works by the identity
  • fastHeadings -- FAST subject headings for works by the identity
  • genres -- genre terms for works by the identity
• title -- A title of a bibliographic record (required if ppn or oclc are not provided)
• wrapper -- An XML node to enclose data returned from Identities (optional, if not provided "facets" is used)
• api -- (Specify "js" to return a JSON object assigned to the JavaScript variable _WCIinfo)
• callback -- (Specify a callback function to return JSON as the function value)
• xslt -- Optional URL for an XSLT stylesheet to embed within XML responses (e.g., to reformat as HTML)