When I first heard about twitter.com, a service that lets people publish messages of up to 140 characters at a time and subscribe to other twitterers’ message feeds, I wasn’t too excited. My second “tweet,” as its users call individual messages (and my last message for four months after posting it) was “I don’t twitter. I barely have time to follow my friends’ blogs. I just signed up to grab the name bobdc in case I ever do want to use it.” If I don’t have time to stay caught up on blogs, why would I care who’s on their second cup of coffee or has too many meetings today?
After I realized that Twitter is a new class of publishing platform, and that serious publishers ranging from The BBC to The Onion are taking advantage of it, I paid closer attention. Its founders view Twitter as a platform, and not simply as a web site for entering and reading these messages, so they’ve provided an API to make it easy to build your own software to send and receive Twitter messages. As I’ll demonstrate, you don’t even need to do any programming to take advantage of it, because free utilities let you make Twitter API calls from your Windows or Linux command line.
The API and Its Documentation
The Twitter API wiki documentation currently divides the API into two categories: the REST API Documentation and the Search API Documentation. The Search API uses a slightly different syntax and is documented separately because it was developed independently at Summize, a company that Twitter has since acquired; while the Search API is still pretty straightforward and RESTful, plans are underway to make it more consistent with Twitter’s other REST API methods.
The search API lets you search for a particular word or phrase in public messages as well as hashtags, which are strings preceded by the # symbol that Twitterers sometimes use to assign a searchable keyword to a tweet. You can also search for messages to, from, or referencing a particular user.
The REST API lets you do just about anything that you might otherwise do with your Twitter account using the forms on the Twitter website. With the API, you can retrieve the last 20 tweets of the accounts you subscribe to, of all unprotected users, or of a specific user. You can send and delete tweets, and you can work with direct messages, friendships, notifications, account blocking, favorite messages, and more—all by sending the right URLs to Twitter’s servers.
To be honest, sometimes it’s not quite that simple. Twitter users can control who sees their messages, and the API complies, ensuring that users can see only messages they’re authorized to see. This means that instead of simply sending the URL to a server (known more technically as performing an HTTP GET) you must also send a valid ID and password to authenticate that you have the right to see the information you’re asking for. In my examples below, I’ll use “twitguy” (currently not a real Twitter ID) as a sample ID and “tgpw” as twitguy’s password.
Most Twitter API URLs have the following structure:
- method_category identifies which set of methods the method belongs to. Twitter’s REST API Documentation page divides the methods up logically into several sets such as status, direct_messages, and account.
- method_name is the specific method to call, such as public_timeline, followers, or update_profile_colors.
- format specifies the format in which you want the server to return information. XML, JSON, RSS, and Atom formats are available for nearly all method calls.
Using the API Without Programming
For Twitter methods that require no authentication, you can invoke a method and read the returned information with any tool that can send a URL to an HTTP server and read the returned text—even with a web browser. For example, let’s say you want to use your web browser to make an API call that asks the Twitter server about messages that mention the RDF query language SPARQL, and you want the results in ATOM. You could enter this URL into your browser without being logged into Twitter:
A web browser isn’t the only application that can do something with a URL. Command-line tools that typically read the name of a local file to process can often read a URL pointing to a remote file as well, as long as the URL contains no characters that might confuse your command line. (Quoting the URL helps.) For example, you can pass a URL instead of a filename to most XSLT processors. The following code (shown here as two lines, but enter it as one) tells the XSLT processor Saxon to run the stylesheet twitteratom2txt.xsl on the URL passed as the first argument, which is a call to a search method of the Twitter API:
java net.sf.saxon.Transform "http://search.twitter.com/search.atom?q=SPARQL" twitteratom2txt.xsl
The brief twitteratom2txt.xsl stylesheet, shown below, converts the Atom representation of Twitter messages to simple text by outputting the message author name, a colon and a space, and the Twitter message (available in both the title and content elements—I used the title version because the content version has extra markup to identify the search term), and two carriage returns.
Here is a bit of the output when using this to search for the term SPARQL with the command line shown above:
padacek (Padacek): http://keg.vse.cz/ - management profoaf:Group/Organization,foaf:Document, vyhledavani resourcu bez popisua trenink SPARQL dotazu.yokofakun (Pierre Lindenbaum): Playing with sparql/myexperiment :-) http://pastie.org/313389SemanticBot (SemanticBot): #SemanticDelicious : RDF and SPARQL: UsingSemantic Web Technology to Integrate t.. http://tinyurl.com/69srfupbacgrad (Luis Casillas): @benbinary Nice. Have you done any work withSPARQL? I've read a couple posts but am looking for some actualexamples. http://is.gd/78L1JeniT (Jeni Tennison): @smyles That seems to be the one, although I'mnot sure it's helpful in my case. More oriented to SPARQL back ends,and def. not RDFa!
The stylesheet could create fancier output, but for such a short stylesheet, it’s a pretty useful output. XSLT processors are just one example of text-processing tools that can accept URL references.
The wget and cURL utilities are both part of the standard Linux distribution, and free Windows versions are easy to find. These tools let you invoke many Twitter API methods from your command line, and because they let you authenticate your call by specifying a Twitter ID and password, you have a wider range of API calls to choose from than browser or XSLT command line invocations allow. The following shows how to use each utility to retrieve XML versions of the 20 most recent messages from twitguy’s friends (the wget command is split onto two lines for display here, but should be entered as one line):
curl -u twitguy:tgpw http://twitter.com/statuses/friends_timeline.xmlwget --http-user=twitguy --http-passwd= tgpw http://twitter.com/statuses/friends_timeline.xml
cURL improves on wget by letting you send an HTTP POST message, which is necessary for Twitter API calls such as the update method that posts a tweet to your account. The following command (split for display here, but to be entered as one line when you try it with your own ID) tweets a classic message to twitguy’s account:
curl -u twitguy:tgpw -d status="having another cup of coffee" http://twitter.com/statuses/update.xml
Programming Languages and the Twitter API
For most popular programming languages, you can find a Twitter API library that lets you send and receive tweets and other Twitter-related information using the syntax and data structures of those programming languages. At this writing, the libraries-for-the-twitter-api Google group lists one API library for each of the Cocoa and Flash/ActionScript languages, two for .NET and Python, three each for Ruby, Perl, and Java, and five for PHP. Twitter’s Twitter Libraries page lists most of these plus additional libraries for C++ and PL/SQL.
If you can take advantage of all of Twitter’s power from the free cURL utility, why use the extra syntax of a programming language? I looked into it for the same reason that I usually learn any new programming language: because after others have done the hard work of writing libraries to perform specific sets of tasks, I can write a bit of code to patch together calls to a set of these libraries and combine their power into something greater than the sum of their parts.
For example, even though I could use cURL to retrieve information about stock quotes, I couldn’t parse out individual pieces of information, take action with that information based on the retrieved values, and assemble the information into complete English sentences that I then publish on Twitter. With the python-twitter library, this was remarkably easy. Next month, in part 2 of this article, I’ll show you just how easy.