Twitter is basically a cut-down blogging service. This article focuses only on the REST API because you really don't need search functionality to publish an RSS feed of tweets. Needless to say, the search API is extremely useful, providing data in Atom and JavaScript Serialized Object Notation (JSON) formats, and allowing a variety of search criteria (tweets containing a word, from a particular user, to a particular user, referencing a particular user, containing a hashtag, and combinations of all the above).
The REST API is equally useful, providing data in RSS, XML, JSON and Atom formats.
Using the Twitter API involves some familiar approaches. In many cases, you can switch from one data type to another just by changing the filename extension. Want Atom instead of RSS? Simply switch the filename extension, and, if the particular method supports it, you get a newly formatted data stream.
Converting your request parameters to 8-bit Unicode Transformation Format (UTF-8) and using Uniform Resource Locator (URL) encoding is also a good idea, particularly if those requests involve complex strings.
It's important to note for your web project that the Twitter API supports the following types of requests:
- GET, which is used for data retrieval
- POST, which is used for submitting, changing, or destroying data
- DELETE, which is also used for destroying data
If you try to retrieve data with a POST operation, the API returns an error — matching methods with request types is a good place to start when debugging.
Table 1. Twitter API status codes
| Code | Description |
|---|---|
| 200 OK | Everything is fine. |
| 304 Not Modified | No new data to return. |
| 400 Bad Request | Invalid request, with some detail. This is also what you get if you exceed the rate limit (more on this in a bit). |
| 401 Not Authorized | You either forgot to provide authentication details, or the ones you provided are invalid. |
| 404 Not Found | The URI you asked for doesn't exist (that is, the user doesn't exist or the data service isn't supported). |
| 500 Internal Server Error | This is usually a problem on the Twitter side of things. |
| 502 Bad Gateway | Twitter is down or being upgraded. |
| 503 Service Unavailable | Twitter servers are overloaded. |
Error messages are always returned in your requested format. If you request XML, you get all error messages in XML. For example, Listing 1 is a snippet of an error message published on the Twitter API wiki.
Snippet of an error message (XML format)
|
One final note about rate limits: Clients are allowed 100 requests per hour, starting from their first request, not including POST updates. Unauthenticated requests are tracked by IP address, while authenticated ones are tracked by the user making the request. Any time you exceed the rate limit, Twitter returns a 400 error message, so you need to think about implementing local caches on your side of things. Public timelines are cached for at least 60 seconds by Twitter, so requesting an update is pretty much a waste of time.
However, if you find yourself bumping up against the rate limit, you can request white listing from Twitter (see Resources). They get back to you within 48 hours, and, if approved, your application is allowed up to 20,000 requests per hour.
Working with the Twitter REST API
When I was just starting out as a young Web developer, I had no problem racing off in any given direction to code away night and day. Fifteen years on, I'm certainly a lot older and, hopefully, a bit wiser. Although I provide some details about some Twitter REST API methods here, it's for informational purposes only. At the end of the day, you're going to use a nice PHP library that eases your pain quite a bit.
However, because it does no good to introduce a library without some context, what follows is a brief discussion of some of the more widely used Twitter REST API methods and calls.
The most commonly used API method is probably public_timeline. It's available, like other status methods, in XML, JSON, RSS, and Atom formats, and is likewise retrieved using a GET method. It's available at http://twitter.com/statuses/public_timeline.xml (or .rss, etc.). The status element, shown in Listing 2, basically contains nodes that describe the account and has an embedded user node that describes the user.
Listing 2. The public_timeline status element
|
Another fairly common method is friends_timeline, which returns the 20 most recent statuses posted by the authenticating user and that user's friends. This is pretty much equivalent to http://www.twitter.com/home if you're logged in to Twitter. The method is available at http://twitter.com/statuses/friends_timeline.xml (or .rss, .atom, .json) and is retrieved via a GET request. You can throw in some optional parameters, such as since (an HTTP-modified date, such as Mon%2C+2+Feb+2009+11%3A45%3A33+GMT) or page (to retrieve a specific page of tweets from the timeline).
Next, there's the user_timeline method, which is similar to friends_timeline but is limited to (you guessed it) a particular user's tweets. If no Twitter username is specified, the API assumes that you want to retrieve the authenticating user's timeline.
There are a lot of other methods available, of course, but these three are enough to get you started. Now, as I alluded to, you can go about messing with the Twitter API without any help, but that doesn't make you a productive developer. You have deadlines of your own, so it's best to use a pre-built library.
The twitterlibphp library contains a list of methods that each map to a Twitter API method. The library itself handles all the connections, authentication, error handling, and the back and forth. Simply include it, authenticate, and use one of the methods to get started.
For starters, see what happens if you use the showUser() method to retrieve an XML status for a particular user. In Listing 3, simply replace the values for $user and $pw with your account's credentials, and that's enough to retrieve status information.
Listing 3. The showUser() method
|
The result provides a lot of information in its raw output. In the XML shown in Listing 4, you not only get to see my real name, screen name, and latest tweet but you can also see who I'm tweeting with, the path to my profile image, and even my color preferences.
Listing 4. Output from the showUser() method
|
Given all this detail, it would be easy to process this XML nodeset with SimpleXML and be able to do something useful with it all. For example, you could easily write a tool that displays the screen_name element along with statuses_count and, perhaps, the created_at node of the most current status.
As interesting as all this is, what you want is RSS. Specifically, you want to retrieve a user's timeline. When you have it in RSS format, you can make it available on a PHP-driven site as a sidebar widget, a unique page, or any other addressable destination.
To do that, change the previous example and use the getUserTimeline() method of the library, shown in Listing 5.
Listing 5. The getUserTimeline() method
|
As you can see, this function returns RSS ready for you to use.
Listing 6. Output from the getUserTimeline() method
|
There is one caveat: You don't want to just repeatedly call this function until you hit the rate limit. Instead, you want to throttle the requests a bit. You can do something pretty clever with the rateLimitStatus()method and some home-rolled caching to achieve local caching effect.
The rateLimitStatus() method, shown in Listing 7, is a simple request that allows you to check whether you've reached your rate limit for the hour — and, no, before you ask, checking the rate-limit status doesn't count against your limit. All you have to do is supply a format and the function does the rest.
Listing 7. The rateLimitStatus() method
|
When you run the rateLimitStatus() method, you get the following XML back.
Listing 8. Output from the rateLimitStatus() method
|
What you want is the value inside the remaining-hits node. If that ever hits five or so (or maybe 10), go to your cached RSS feed instead. With this XML nodeset available to you, all you have to do is load SimpleXML to quickly parse the rate-limit status. Of course, if you're not familiar with the vagaries of XML, it might be better to parse out JSON.
Running the same code using the JSON format yields a much more compact statement:
{"remaining_hits":95,"hourly_limit":100,"reset_time":"Mon Feb 02 05:44:45 +0000 2009",
|
You could take the time to split out this string by comma and then again by colon to grab the value of remaining_hits. That's simple enough, of course. However, if you're running PHP V5.2.0 or higher, it's likely that you already have the json_decode() method available to you. As shown in Listing 9, all you have to do is use that function to pull out the remaining_hits number, then use a simple if statement to see if that number is anywhere close to 10 or lower. If it isn't, pull the RSS feed from Twitter, but save it to a file for later. If it is lower than 10, serve the saved RSS file cached locally.
Listing 9. Using the json_decode() method
|
