ActionScript and the Twitter API, Simplified

The API is one of the best things about Twitter. It gives developers the power to take this mass of accumulated ephemeral chattering and come up with many interesting ways of interacting with the data. But the API has its quirks, which makes accessing it from Flash or Flex a slightly rocky road at times.

The aim of this tutorial is to simplify matters, and get you making your first AS3 Twitter requests (using either Flash or Flex) within a few minutes. I have condensed the process down to three easy steps.

STEP 1: DECIDE WHAT YOU WANT TO ASK

Getting an answer becomes a lot easier once one has decided upon the question.

All requests to the Twitter API are HTTP based, which means they are no more complicated than calling a URL, with certain parameters passed via GET (occasionally POST). This means that before we even need open Flash/Flex we can test most of our API calls in the web browser.

Lets start by reading a user’s timeline. To return the last five tweets by user “zenbullets” you would request …

http://twitter.com/statuses/user_timeline/zenbullets.xml?count=5

… which will return an XML. The “count” variable specifies how many tweets you want returned (to a maximum of 200 currently).

If you want the public timeline, call:

http://twitter.com/statuses/public_timeline.xml?count=5

Or, to get a single tweet, reference it by id:

http://twitter.com/statuses/show/1393549185.xml

You can also change the file extension from .xml to .json, .rss or .atom to return the data in a different format, eg. RSS:

http://twitter.com/statuses/user_timeline/zenbullets.rss?count=5

More interesting results can be gleaned by performing searches on the public timeline. This involves calling a separate API at http://search.twitter.com/, and passing it a few GET parameters.

Some examples:

http://search.twitter.com/search.atom?q=flashbrighton – all tweets mentioning “flashbrighton”
http://search.twitter.com/search.atom?q=from%3Azenbullets – all tweets from user “zenbullets”
http://search.twitter.com/search.atom?q=flashbrighton+from%3Azenbullets – all tweets from user “zenbullets” that refer to “flashbrighton”

Parameters include “from:”, “OR”, “+” etc., and can be combined to form advanced queries. The full list of operators is here. You’ll notice the parameters need to be URL encoded, eg. “from:” becomes “from%3A”. Two common encodings you might need are “%3A” for the “@” in @replies, or “%23″ for the hash tag “#”.

Note also that search requests can only be returned in either ATOM or JSON format.

Ok, so we’ve got a query, we’ve tested it in the browser. Next we need to request this data from ActionScript.

STEP 2: MAKE THE REQUEST

You know how to make a URL request in ActionScript don’t you? Of course you do.

For the example below I decided I wanted to get a list of all the tweets where one user referred to another:

var _twitterXML:XML;
var _user1:String = "zenbullets";
var _user2:String = "yezzer";

var urlReq:URLRequest 
    = new URLRequest("http://search.twitter.com/search.atom?q=" 
    + _user1 + "+from%3A" + _user2);
var loader:Loader = new Loader();
loader.addEventListener(Event.COMPLETE, SuccessFunc);
loader.addEventListener(IOErrorEvent.IO_ERROR, IOError);
loader.addEventListener(SecurityErrorEvent.SECURITY_ERROR, 
     SecurityError);
loader.load(urlReq);

private function SuccessFunc(e:Event):void {
    if (e.target.data) { _twitterXML = new XML(e.target.data); }
}

private function IOError(e:Event):void {
	// handle error
}

private function SecurityError(e:Event):void {
	// handle error
}

All this does is call a URL on search.twitter.com and place the returned XML into a variable _twitterXML.

This method works fine with any request for unprotected public data. Things get a little more complicated if you want to access any of the functionality available to a logged in user, e.g. posting updates, reading Direct Messages, or accessing your friends timeline. All these feats can be performed by an authenticated user (i.e. one who has logged in). To do this from ActionScript you should use the OAuth protocol to get a login token before making requests.

But this is the “simplified” tutorial, so I’ll leave you to google this for yourselves rather than going off on a tangent here. Twitter also support Basic Access Authentication too, if you are after a quick, hacky (and less secure) solution. The list of methods available to authenticated users can be found within the Twitter API Documentation.

Lets now look at what we can do with the data we get back.

STEP 3: PARSE THE XML

This is probably the trickiest bit. Firstly, the XML is different depending upon which format we have chosen for the data (XML, RSS, ATOM) obviously, but it also differs depending on whether our call was to the Search or REST APIs (ie. search.twitter.com or www.twitter.com). So, in the name of keeping things simple lets just look at one of these cases – a response from the Search API (the most versatile of the two), in ATOM format.

If we analyse the XML returned from the example in Step 2, we can see that, after a bit of header information, the tweets are denoted by a stream of <entry> tags.

<entry>
    <id>tag:search.twitter.com,2005:1761695534</id>
    <published>2009-05-11T09:11:28Z</published>
    <link type="text/html"  ... />
    <title>Good to see evidence of Midlands New Media 
http://flashcamp.co.uk/ Tempted to go up to check out 
the talent. @yezzer @Little_Robot</title>
    <content type="html">Good to see evidence of Midlands New Media 
&lt;a href="http://flashcamp.co.uk/"&gt;
http://flashcamp.co.uk/&lt;/a&gt; 
Tempted to go up to check out the talent. 
&lt;a href="http://twitter.com/yezzer"&gt;@&lt;
b&gt;yezzer&lt;/b&gt;&lt;/a&gt; 
&lt;a href="http://twitter.com/Little_Robot"&gt;
@Little_Robot&lt;/a&gt;
</content>
    <updated>2009-05-11T09:11:28Z</updated>
    <link type="image/png" ... />
    <twitter:source>TweetDeck</twitter:source>
    <twitter:lang>en</twitter:lang>
    <author>
      <name>zenbullets (Matt Pearson)</name>
      <uri>http://twitter.com/zenbullets</uri>
    </author>
  </entry>

We might assume that we can access a list of the text of all tweets with a statement like

var _tweetList:XMLList = _twitterXML.entry.title;

But no. I’m afraid it’s not that simple because all of the tags in this XML belong to namespaces. The tag <entry> is actually <http://www.w3.org/2005/Atom::entry>. Don’t worry if you don’t understand namespaces – they are a huge pain in the arse in ActionScript. I’m going to show you a little bit of code to get round them.

It is possible to just rip out the namespaces from an XML, but I find I’m more comfortable filtering out what I need using the rather obscure localName property of XML nodes. This code will loop through the TwitterXML and extract the <entry> tags:

var _tweetList:XMLList = _twitterXML.children();
for (var x:int = 0; x < _tweetList.length(); x++) {
	if (_tweetList[x].name().localName == "entry") {
            // it's a tweet, process it
       }
}

The same goes for the elements within the Tweet. We’ll probably be most interested in the <title> and <content> tags, which contain the actual tweet itself in text and HTML formats. Lets add another parsing loop within the previous parsing loop to put these elements into an array.

var _titleArr:Array = new Array();
var _contentArr:Array = new Array();

var _tweetList:XMLList = _twitterXML.children();
for (var x:int = 0; x < _tweetList.length(); x++) {
	if (_tweetList[x].name().localName == "entry") {
            var thisTweet:XML = _tweetList[x];
            var nodes:XMLList = thisTweet.children();
            for (var y:int = 0; y < nodes.length(); y++) {
	        if (nodes[y].name().localName == "content") {
		   _contentArr.push(list[y].text());
	        } else if (nodes[y].name().localName == "title") {
		   _titleArr.push(list[y].text());
		}
	     }
       }
}

And there you have it. You have successfully harnessed your Tweets into arrays, ready to be herded into whatever application you have for them. It’s all worked so far, hasn’t it? HASN’T IT?

BONUS STEP: WHY DOESN’T IT WORK FOR ME …

All of the above should work, and publish to the web without issue. But I have cheated slightly by using search.twitter.com for my example, rather than www.twitter.com. If I were to go the correct API route, and use authenticated requests to the REST methods at www.twitter.com (notice how I glossed over those rather quickly) we would have come up against one final obstacle; Twitter’s cross-domain security restrictions. (search has a much friendlier cross-domain policy)

There are ways to climb every mountain though, and if you have managed to work out authentication, you should have no problem creating a PHP Proxy to bypass the security restrictions.

It’s not as scary as it sounds. It is only Flash Player that is limited by cross-domain policy files. If we make the API request from PHP we can bypass the security restriction.

The following two lines of PHP code will create your proxy service. Name this proxy.php and put it on your server:

<?php 
$url = $_GET['url'];
readfile($url);
?>

Now, instead of calling

http://twitter.com/statuses/user_timeline/zenbullets.xml?count=5

We call

http://yourserver.com/proxy.php?url=http://twitter.com/statuses/
        user_timeline/zenbullets.xml?count=5

This is all that is required to fool the cross-domain policy. This, ladies and gentlemen, is what we call a hack.