Get Started With the Twitter API

Current revision

The microblogging site with the funny name is one of the hottest web services around.

Introduction

Twitter is one of those websites with very little room for functional nuance. Its limit of 140 characters per post forces users to be succinct, something that makes many people feel over-constrained and leads them to view the service as too simple to actually be useful. Others see unbridled freedom inside such a unique limitation and embrace it like a poetic device. The lesson: You either get Twitter or you don't.

Regardless of how you feel about it, if you're looking to try out an API for the first time, Twitter is a great place to start.

Like the service itself, the Twitter API is simple and easy to use. The only thing to keep in mind is that Twitter limits you to 70 requests per 60 sixty minute interval, so remember to cache or otherwise store your results. Otherwise, you may find yourself banned.

If you end up building something that needs to make requests more frequently, you can always e-mail Twitter and ask for permission.

Steps

Getting Started

Twitter's API is REST-based and will return results as either XML or JSON, as well as both RSS and ATOM feed formats.

For a very simple look at a typical data response fire up a terminal window and type:

curl http://twitter.com/statuses/public_timeline.rss

That line will give you the latest 20 tweets from the public timeline in the form of an RSS feed. To get the same results in JSON just change the extension to ".json".

Public timelines can be accessed by any client, but all other Twitter methods require authentication.

Authenticating with Twitter

To authenticate yourself to Twitter you need to send a username and password. The basic format is:

curl -u email:password http://twitter.com/statuses/friends_timeline.xml

Most client libraries offer easy ways to pass in a username/password pair, making it very simple to authenticate with Twitter.

Client Libraries

There are already some pretty good libraries out there for accessing Twitter, and there's no need to re-invent the wheel. Whatever you're looking for, Twitter's got it: ActionScript, Python, Ruby, PHP and many more.

Using Python with Twitter

For the sake of example, we'll use the Python library. Download and install the library and fire up a terminal window.

Let's grab your last twenty tweets. Fire up Python and type the following line, replacing "youusername" with your username:

>>> import twitter
>>> client = twitter.Api()
>>> latest_posts = client.GetUserTimeline("yourusername")
>>> print [s.text for s in latest_posts]

The last line prints out just the text of your posts. To get at things like date pasted and other useful methods, have a read through the Python library documentation.

To go the other direction (posting something to Twitter) we'll need to authenticate. Recreate our Twitter client, but this time pass in your username and password:

>>> client = twitter.Api(username='yourusername', password='yourpassword')
>>> update = client.PostUpdate('The Twitter API is easy')

Head over to your Twitter page and you should see the update.

Suggested readings

Mashups, Apps and More

To get some idea of what you can do with the Twitter API, visit the fan wiki and check out some of the applications and mashups created by Twitterheads.

Hashtags

One area of particular usefulness is the hashtags concept. Hashtags involve inserting a # sign to denote keywords or other data like location. Although not everyone is a fan of hashtags (they tend to make your tweets less readable) parsing Twitter streams for hashtags can yield a wealth of useful data.

Some of the client libraries include functions to parse hashtags, but in many case you may have to write your own functions.

Full API documentation

You can check out the development talk for the full api documentation.

• This page was last modified 06:00, 5 August 2008.