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.