Monday, April 20, 2009

How to Use the Arc90 PHP API to Get Info From Twitter

I recently decided, as a programmer and self-proclaimed web developer, to dive into the Twitter API, mostly just for fun.  From the main Twitter API Page you can access a series of prebuilt libraries for various programming languages, which provide wrappers around the main Twitter API.  With PHP being my web developing language of choice, I quickly glanced over the libraries available, with one clearly standing out: Arc90.  Not only is it maintained by a fellow "Matt," it also provides access to mostly anything you could think of in the world of Twitter.  By the end of this article, you should be able to pull all of your followers from Twitter and list some basic data about them.

Installation and Environment: The main page for Arc90 provides a very basic introduction on how to install and use the package, which is sufficient for getting your PHP environment ready to use.  So, for the purpose of this, I will assume that your PHP environment is all set, your includes are in order and cURL is ready to go.  If you need further help with any of those areas, feel free to leave a comment below.  So, I will assume you have a set up like the following:

  1. <?php  
  3. require_once('Arc90/Service/Twitter.php');  
  5. $twitter = new Arc90_Service_Twitter('username''password');  
  7. try  
  8. {   
  9.     // Gets the users following you, response in JSON format  
  10.     $response = $twitter->getFollowers();  
  12.     // Store the JSON response  
  13.     $theData = $response->getData();
  15.     // If Twitter returned an error (401, 503, etc), print status code  
  16.     if($response->isError())  
  17.     {  
  18.         echo $response->http_code . "\n";  
  19.     }  
  20. }  
  21. catch(Arc90_Service_Twitter_Exception $e)  
  22. {  
  23.     // Print the exception message (invalid parameter, etc)  
  24.     print $e->getMessage();  
  25. }  

  26. ?>
Note a few changes: Obviously, on line 5 you will need to replace 'username' and 'password' with your login credentials.  On line 10, I went ahead and removed the parameter to request an XML response.  I saw that the default was JSON and wanted to try that (since that is another new technology for me).  I'm also using the getFollowers() API call instead.  On line 13, I'm storing the returned data for future use. 

Important Note Regarding API Rate Limits: If you are unfamiliar with Twitter and its associated API calls, you need to make sure that you don't overdo it on the number calls you make.  By default, Twitter allows you to have 100 API calls per hour (this includes using third party applications like TweetDeck or Nambu), so you'll need to keep an eye on how many calls you're using.  If you go over that limit, you can potentially be blacklisted -- which makes no one happy.  You have a couple of options: 1) Request to be whitelisted using this form.  This will allow you to use 20,000 requests per hour, or 2) Watch your rate limit using a built-in API method which monitors your status, and conveniently does not cost you an API call to use.  You can find more info regarding limits, whitelisting and blacklisting here.  Also, during development, I've gone and saved the output to a particular API call to a text document that I can parse while I test.  It doesn't provide real-time data, but it allows me to work on it as many times as I want without a single API call.

Using the Data: Now that we have our data response in JSON format to work with, let's get to it! To make good use of the data returned, I chose to put it in an associative array for organized access.  To do this, we use the json_decode method built into PHP as follows:
$dataArray = json_decode($theData, true);
To view an example of the kind of data that a getFollowers API call will return, we can view this method page in the documentation.  Also, for a detailed description of each key that can possibly be returned from any of the various API calls, you'll want to keep the complete list handy.  I ended up making a spreadsheet with the various API calls that I tested along with the associated return values, for a quick reference -- so you may want to do the same.

Let's say that we just want to loop through our followers (or at least the first 100) and print out some data about each one, line by line.  All we have to do is iterate through the array, pulling out the data we want and display it.  I stuck with a basic HTML table for this, but all you CSS gurus out there can have way more fun with this.  This assumes that you already have your associative data array, dataArray, ready to go:
  1. <html>
  2.         <head>
  3.             <title>Test</title>
  4.         </head>
  5.         <body>
  6.             <h1>Followers</h1>
  7.            <table border="1">
  8.                 <tr>
  9.                     <td>Image</td>
  10.                     <td>Screen Name</td>
  11.                     <td>Name</td>
  12.                     <td>Description</td>
  13.                     <td>URL</td>
  14.                     <td>Location</td>
  15.                     <td>Following</td>
  16.                     <td>Followers</td>
  17.                     <td>Status</td>
  18.                     <td>Status Count</td>
  19.                 </tr>
  20. <?php
  21.     $numItems = count($dataArray);
  22.     for($i = 0; $i < $numItems; $i++){
  23.         $currentItem = $dataArray[$i];
  25.         $screenName = $currentItem["screen_name"];
  26.         $description = $currentItem["description"];
  27.         $followersCount = $currentItem["followers_count"];
  28.         $url = $currentItem["url"];
  29.         $name = $currentItem["name"];
  30.         $status = "";
  31.         if(isset($currentItem["status"]))
  32.         {
  33.             $status = $currentItem["status"]["text"];
  34.         }
  35.         $friendsCount = $currentItem["friends_count"];
  36.         $profileImage = $currentItem["profile_image_url"];
  37.         $location = $currentItem["location"];
  38.         $statusCount = $currentItem["statuses_count"];
  39.          echo "<tr><td><a href='".$screenName."'><img height='48' width='48' src='".$profileImage."'></a></td><td>".$screenName."</td><td>".$name."</td><td>".$description."</td><td>".$url."</td><td>".$location."</td><td>".$friendsCount."</td><td>".$followersCount."</td><td>".$status."</td><td>".$statusCount."</td></tr>";
  40.     }
  41. ?>
  42.     </table>
  43. </body>
  44. </html>
 You should end up with something that looks like:

If you have any trouble working through this, or have any questions, just let me know!

Monday, April 13, 2009

Dipping My Toes in the Twitter Pool: A Beginner's Analysis

There's no doubt that the micro-blogging service Twitter has exploded in popularity within the last month or so. More and more websites and blogs seem to have Twitter accounts, and the service doesn't seem to be going away anytime soon -- even though they do have trouble from time to time supporting the demand. Being the person that I am, I had no choice but to check out Twitter and create an account, so I could check out this flourishing service for myself.

If you are a power Twitter user, or feel like you are already comfortable with the service, this post probably isn't for you. But, if you're new to it, trying to make sense of everything, I hope this will at least give you a little insight. Here are my discoveries:
Setting up a Bio: I tend to fall on the paranoid side of things when it comes to privacy on the Internet. I'm always concerned anytime I enter information even as simple as an email address -- You can imagine, I really didn't know what to put in my bio. So, at first, I didn't put anything. After previewing a few different accounts, I've at least decided to improve upon that. I have added my name (just my first name for now) and a quick description of what I'm interested in and what I do. There's now even a nice little mugshot up there. I've come to the conclusion that it's very important to have personal and relevant information about yourself in your bio. Other users like to be able to put a face with a name, and if you're trying to build a community of users with similar interests, telling a little bit about yourself is just as important. Plus, you're proving to other users that you're not just a bot when you follow them (more on that in a bit).

Public Versus Protected Updates:
Twitter gives you the option to protect your updates. If you choose this mode, your updates will not be visible to anyone but those you grant explicit rights to, as you will have to approve every follower individually. Naturally, I started down this path, being on the privacy paranoid side of the fence. Once I began to better understand what I believe to be the purposes of the Twitter service, I decided to remove that restriction -- now I just make sure that I don't post any updates that are too revealing.

Following, Followers and Blocking:
At first, I was really unsure of who I should be following. I did a quick search through my email contacts and discovered that only a couple of my friends were on Twitter -- so I followed them. So, that left me with a few people I was following and even fewer followers. To really utilize Twitter, and all that it can offer, following people you haven't met in person is a must. My first venture into adding new users to follow was going through the users that my friends were following. I figured, hey, if they're interested in a particular user, I may be as well. Once I was done with that, really all I had left to do was search. Now, at this point, one thing that Twitter is really lacking is a good way to search for people you would probably be interested in following. However, there are other websites that have capitalized on this lack of search (We Follow is the directory I currently prefer, @wefollow). Followers, on the other hand, can be a little bit harder to come by -- which in my opinion, is a good thing. I really see Twitter as a great place to get real time feedback from a community of users with similar interests and occupations. However, sometimes followers come a little too easily. Every time I'm notified that I have a new follower, I check out their bio to see who they are. If they seem to be a bot of any kind, any kind of random marketer, someone who is just trying to increase their own follower count, or otherwise not a regular human, I actually block them from following me. I'm still not sure if this is the "proper" way of handling this, but it seems to be working out fine so far -- I don't want to follow anyone like that, and really, as people look through my followers, I wouldn't want to be associated with anything like that either.

Twitter as a News Source: One thing that I absolutely love about Twitter is the real-time aspect of it. With that comes real-time news updates. The best all-around news source that I've discovered up to this point is Breaking News (@BreakingNews). There are several other technology-related websites that I also follow on Twitter that provide close to real-time updates in the world of technology. At this point, I really can't consider Twitter as a viable alternative to RSS. I use Google Reader for dozens of feeds (including items my friends have shared), and I like the ability to go back and view the titles and brief overviews as I have time, and be able to email the stories to friends and family, as well as comment on stories with other Google Reader users. Until there is a better way to organize, preview and share all of those news stories in Twitter, I think I'll just stick to the headlines for now.

Battle of the Twitter Clients: There really seems to be a "Gold Rush" type opportunity for those building Twitter clients at the moment. In my opinion, the frontrunners in the Windows world are TweetDeck (@TweetDeck) and Twhirl/Seesmic Desktop. And then on Mac OS X, TweetDeck and Nambu (@NambuCom) are the clients I'm currently keeping up with. If you're not using a third-party Twitter client, you're really missing out on the full potential of the service. For example, with TweetDeck, you can use a multi-column layout that allows you to filter tweets based on different criteria (such as by groups of users that you define, or a search on Twitter, or all of your direct messages, etc.). Also, with TweetDeck, you can tie into your Facebook account and set up another column for all of your Facebook Friends' status updates. Options like these make having a third-party client priceless.

Don't Worry About it: Above everything else, don't worry about the number of followers you have, or if you can't think of what to post. It really does take some time getting used to the environment and the community of users out there. But, if you do invest the time, Twitter can really be used to enhance your experience on the web, build a community of new friends, and keep up with what's going on in the outside world. The important thing is to be yourself, and post things that are relevant to you. Or, if you really like what someone else has posted, feel free to re-post it (giving them the appropriate credit of course.) So, if you've made it all the way to the end of this and have any additional advice you'd like to add -- or have any questions you think I may be able to answer, feel free to leave a comment below!