Editor's note: Meerkat predated the popularity of syndication, feed services, and feed readers. Now that other groups are providing this service, we have removed Meerkat in favor of their better solutions. We maintain these articles for the sense of historical interest.
Meerkat, O'Reilly Network's Open Wire Service, extends its open API with XML-RPC, affording a more standardized XML-based interface to its aggregated RSS database.
Meerkat's API is "URL-line"; similar in concept to the Unix command-line, Meerkat's engine may be queried over the Web using combinations of various arguments.
The URL-line interface is rather common in the web-scripting world. A script's URL is postfixed with "?" and one or more "&"-separated "key=value" pairs representing variables and their associated values. With the emergence of CGI scripting, the URL-line became the Web's command-line interface. The URL-line is lightweight, bookmarkable, simple
The RPC in XML-RPC stands for "Remote Procedure Call," a fancy way of saying that you're calling procedures (functions, subroutines, or methods) on another, remote, server. Just like a URL-line CGI script, arguments are passed and results returned; the difference is only in the serialization (the way it's written), which here, as the name suggests, is XML. XML allows for richer message-passing between client and server. For more information on XML-RPC, pointers to language implementations, and a quick read of the specification, visit XML-RPC.com.
Meerkat's XML-RPC API is a direct port of its straightforward URL-line recipes to an RPC environment. Written (as with the rest of Meerkat) in PHP, it uses Edd Dumbill's PHP XML-RPC modules. These provide simple, clean implementations of both client and server -- I highly recommend them!
Meerkat's XML-RPC server is at the URL:
The server supports five methods: introspection, getCategories, getChannels, getChannelsByCategory, getItems. We'll go through each of these in detail. For demonstration and edification purposes, I've provided a link to Meerkat's live test suite for each of the methods.
Signature: array system.listMethods()
This method lists all the methods (including itself) that Meerkat's XML-RPC server knows how to dispatch. It returns an array of structs of method names, their signatures, and documentation.
Signature: array meerkat.getCategories()
Returns an array of structs of available Meerkat categories, each with its associated category ID.
Signature: array meerkat.getChannels()
Returns an array of structs of available RSS channels, each with its associated channel ID.
Signature: array meerkat.getChannelsByCategory(int)
Returns an array of structs of RSS channels in a particular category (specified by integer category ID), each with its associated channel ID.
Signature: array meerkat.getItems(struct)
Returns an array of structs of RSS items given a recipe struct. The getItems method makes full use of Meerkat's powerful recipes (read: query parameters). The following is a complete list of parameters from which to build a recipe:
Here's a simple PHP-based example, searching three days' worth of the xmlhack channel for any mention of XML or Java and returning IDs, descriptions, categories, channels, and dates. Only the latest five items are requested.
$f = new xmlrpcmsg("meerkat.getItems", array( new xmlrpcval( array( "channel" => new xmlrpcval(724, "int"), "search" => new xmlrpcval("/XML|[Jj]ava/", "string"), "time_period" => new xmlrpcval("3DAY", "string"), "ids" => new xmlrpcval(0, "int"), "descriptions" => new xmlrpcval(200, "int"), "categories" => new xmlrpcval(0, "int"), "channels" => new xmlrpcval(0, "int"), "dates" => new xmlrpcval(0, "int"), "num_items" => new xmlrpcval(5, "int"), ), "struct" ) ) );
Here's a little sample code to get you on your way. There are implementations for various programming languages available at XML-RPC.com. I've chosen PHP, Perl, and Python for my examples.
Sample 1: PHP
A PHP code snippet for retrieving and printing all of Meerkat's categories.
Sample 2: Perl
A Perl script using Ken MacLeod's Frontier::Client module, part of his Frontier-RPC XML-RPC toolbox. This script retrieves and prints the component channels of Meerkat's Perl category.
Sample 3: Python
An interactive Python session using PythonWare's xmlrpclib to search Meerkat for the latest five stories on Python. Descriptions, turned on by default, have been disabled for brevity's sake in this example.
Hopefully I've succeeded in providing an API that will be useful to you in building your application -- or just to fiddle with or learn from. As usual, I welcome any constructive criticism you might offer. Please post your suggestions, bug reports, and other feedback (maybe praise?) to the O'Reilly Network RSS Forum.
And, if you're so inclined, spread the Meerkat word with a nifty "Meerkat Powered!" button. To do so, simply copy-and-paste the following HTML into your document:
<a href="http://meerkat.oreillynet.com"><img src='http://meerkat.oreillynet.com/icons/meerkat-powered.jpg'></a>
Rael Dornfest is Founder and CEO of Portland, Oregon-based Values of n. Rael leads the Values of n charge with passion, unearthly creativity, and a repertoire of puns and jokes some of which are actually good. Prior to founding Values of n, he was O'Reilly's Chief Technical Officer, program chair for the O'Reilly Emerging Technology Conference (which he continues to chair), series editor of the bestselling Hacks book series, and instigator of O'Reilly's Rough Cuts early access program. He built Meerkat, the first web-based feed aggregator, was champion and co-author of the RSS 1.0 specification, and has written and contributed to six O'Reilly books. Rael's programmatic pride and joy is the nimble, open source blogging application Blosxom, the principles of which you'll find in the Values of n philosophy and embodied in Stikkit: Little yellow notes that think.
Discuss this article in the O'Reilly Network RSS Forum.
Return to the O'Reilly RSS DevCenter.
Copyright © 2009 O'Reilly Media, Inc.