From the archives: How we built the WorldCat Facebook App using the WorldCat Search API

Bruce Washburn /

Way back in 2007, when Facebook was new and interesting to me, as part of my work in testing how the WorldCat Search API would behave in the real world I wrote a Facebook app that would search WorldCat.  

We haven’t changed the app much over time: it has received some attention and use, but the evolution of the Facebook application ecosystem and the general lack of social features in the app worked against its widespread adoption.  But in case the approach we took is of interest to other Facebook application developers, here are some notes on how our app was constructed back then.  

Like other Facebook apps of similar vintage, I wrote ours in PHP, employing a handful of the built-in FBML markup elements that Facebook supplies.  And we kept the interactions pretty simple: “keyword searching for known items” was the expected use case so the app shows brief results sorted by relevance, with the opportunity to link on to a more fully-featured web experience (WorldCat.org) as needed.

Screen capture

The initial page for the app starts its work by looking up a set of keys it will need for identifying itself to Facebook, and adding in the PHP libraries Facebook supplies.  With these keys and those libraries, the app can do simple Facebook things (if the app’s user has allowed them), such as getting their name, location and interests from their profile.  We use all 3 of those in our app: the name to personalize it (e.g., “Hello Bruce!”), the location to modify WorldCat.org links to show nearby libraries, and the interests to do an initial keyword search for a randomly selected interest in WorldCat.

These values are pretty easy to look for, using Facebook’s code in PHP.  E.g., to get the app user’s zip code:

$profile_array = $facebook->api_client->users_getInfo($fb_user,'current_location');
$zip = $profile_array[0]['current_location']['zip'];

My app’s home page includes a WorldCat search box and search result.  Searches are sent to the WorldCat Search API and formatted for display in HTML within the app, and individual records are linked to WorldCat.org using the record’s OCLC number and (if available) the user’s zip code.  The Search API requests are keyword searches, using the SRU protocol and Dublin Core XML responses. My app used PHP CURL to send the Search API request and get the result.

Back in 2007 I parsed the XML directly in my PHP code, but knowing what I know now I might handle it as a PHP array:

$array = simplexml_load_string($contents);

Or maybe convert that array to JSON:

$json = json_encode($array);

(The PHP simplexml_load_string method isn’t always happy with XML namespace declarations, and we multiple namespaces in our XML responses, so I might cheat by string-substituting those away before creating the array.  There’s undoubtedly a better way to do this in PHP … I’d be happy to learn it.)

So, once I have the result I have a simple PHP loop to look at certain values in each record, some to display, some to serve also as links.  I’m displaying the DC title, creator, publisher, date, and description in my brief results, also picking up the OCLC identifier to link the title to WorldCat.org.  If I have the user’s zip code, I tack that onto the end as “?loc=[zip]” so that WorldCat.org’s list of nearby libraries will be based on that.  Some of the descriptions can be lengthy, so I arbitrarily truncate them after about 400 characters.  

I also linked the author to WorldCat Identities.  If you know the author’s last name and the OCLC number of their record, you can create the link this way:
http://worldcat.org/identities/find?url_ver=Z39.88-2004&rft_val_fmt=info:ofi/fmt:kev:mtx:identity&rft.namelast=[last name]&rft_id=info:oclcnum/[oclc number]
Thanks to Thom Hickey for the linking advice: http://outgoing.typepad.com/outgoing/2008/06/linking-to-worl.html

The app has other features, like an advanced search screen, a list of “something to read” suggestions, a way to register your WorldCat list and see the registered lists of your friends, etc.  I used the FBML “tabs” code to create a tabbed interface to these other screens:

<fb:tabs>
      <fb:tab-item href='http://apps.facebook.com/worldcat/index.php' title='Home' selected='true'/>
      <fb:tab-item href='http://apps.facebook.com/worldcat/advanced.php' title='Advanced' />
      <fb:tab-item href='http://apps.facebook.com/worldcat/toread.php?list=worldcatlists' title="Something to Read" />
      <fb:tab-item href='http://apps.facebook.com/worldcat/worldcatlist.php' title="Favorite WorldCat Lists" />
      <fb:tab-item href='http://apps.facebook.com/worldcat/invite.php' title="Invite Friends" />
      <fb:tab-item href='/board.php?uid=[user id]' title="Contact Us" />
</fb:tabs>

There are other FBML tags to quickly build UI components, such as fb:title for the page title, fb:name uid=”[user id]” for the Facebook user name, fb:share-button class="url" href="[app url]" to create a “Share” button, and more.

So, a Facebook app isn’t all that hard to assemble.  What’s much more difficult is finding the right mix of features to attract and retain attention in Facebook; the track record of library-centric Facebook apps and pages suggests that it can be an uphill climb.  As with any other web application, knowing your users and meeting their needs is crucial.   

Have you built a Facebook app for your organization? What worked? What didn't? We can start a discussion thread over in Groups, if you like.