Introduction to the Twitter API

(Note: Post from my old blog)

The last weekend, I played around with the Twitter-API and I would like to share some experiences.

Due to historical reasons (see this blog entry for more info), there are in fact two separate Twitter-APIs. The interface providing access to the core functionalities is called “REST API“, the second set of services is designated “Search API“.

Both interfaces are based on the REST standard. Reading information requires a GET, submitting and changing information demands a POST and deleting information is made using a DELETE request.

The REST API:

Basically, all URLs follow one of these templates:
http://twitter.com/[Category]/[Function].[Format], or
http://twitter.com/[Category]/[Function]/[Object].[Format]

The [Format] part specifies in which format the return data has to be delivered. Supported are currently RSS, ATOM, XML and JSON.

This first example gets the public timeline in RSS format (just click to try it in your browser). It uses the “[Category]/[Function].[Format]” template:
http://twitter.com/statuses/public_timeline.rss

The second example returns the public tweets from the user ‘javaposse’ in XML format. It uses the “[Category]/[Function]/[Object].[Format]” template:
http://twitter.com/statuses/user_timeline/javaposse.xml

Obviously, functions that allow modifying information, reading your private messages or consulting protected user tweets require an authentication. Twitter supports two methods of authentication: the classic “Basic Authentication” (sending user name and password as part of the HTTP request) and, as of this year, the OAuth protocol (you can decide who to give access to your information via tokens).

Just click this to try the basic authentication:
http://twitter.com/direct_messages.rss

When no alternative indication has been given, most of the API functions return the last 20 records (like tweets and friends). Typically, failures are returned as HTTP error codes (i.e. RESTfull) with an additional message in the requested format (XML, JSON, etc.). Alternatively, the user can request to get a permanent OK answer, completed with extended error information in the message body.

The Twitter server limits the number of requests per time period, based on client IP or user ID, depending if the method requires an authentication or not. The standard limitation, i.e. without having a dedicated agreement with Twitter, is quite restrictive. More information about this can be found on the dedicated pages.

The Search-API:

This set of services allows searching all public tweets for a free text (as the Twitter search page does) or a few other parameters. Additionally, it’s possible to download trends. At the time being, there is no real integration with the REST API. Less output formats are supported (only JSON and ATOM) and the user identification works differently.

I didn’t test this interface much, so I refer the online documentation for more details.

Libraries

Of course it’s nice to know all this, but you really don’t need to implement  the interfaces by yourself. There are plenty of libraries for most of the classic programming languages available on the net. On the Twitter site, you can find a directory.

Links

The Twitter API Homepage

Libraries implementing the APIs

List of methods and functions

Rate limits

Et zou…

There are plenty of funny things you can do using Twitter and I hope after reading this little introduction, you are fancy to try some (maybe new) ideas

Leave a Reply

Your email address will not be published. Required fields are marked *