Update: March 2013

This method of retrieving timeline data from Twitter is going to be shut down very soon. Please see my follow up article on the death of the Twitter API v1 for more details on why it will no longer be possible to use JavaScript for the Twitter API.

Twitter. For better or worse it’s everywhere. You’d be hard pressed to find a new website or blog that is not incorporating a twitter feed into the site somewhere. There are tons of plugins, libraries, and extensions that help you get up and running with a twitter feed quickly, but many times they can be overkill for what you need.

One of the great things about twitter is how accessible it is. The team at twitter has done a really good job of creating an API that is simple, powerful, and flexible all at the same time. If you just need to read a single timeline (your own or someone else) you can skip all the 3rd party plugins and libraries and just roll your own JavaScript solution.

The example I’m going to discuss could be used to read a list of status updates for a user, or just the latest tweet, and display it anywhere you like in a website or blog. For convenience sake I’m using jQuery since we are generally using it in every project these days anyway.

Getting the data URL

Twitter’s API is pretty straight forward, you can get to whatever data you need with ease by reading their REST documentation. In our case, we are using the Get Statuses method call. The syntax is:

https://api.twitter.com/1/statuses/user_timeline/CypressNorth.json?callback=?&count=1

In our case we are limiting the response to 1 because we are only concerned with the latest tweet. If you remove the count parameter you get back the most recent 15 status updates. You can use the same URL to get the timeline of the account you are interested in, just replace cypressnorth.json with youraccountname.json.

Similarly, if you’d prefer to work with XML, you can change the extension of the request to youraccountname.xml and XML will be returned.

Making the AJAX Request

Now that we know the URL to retrieve our data, it’s time to make the request. In my case I’m only interested in working with JSON data, so to save time I can use the jQuery $.getJSON() function to both make the request and parse the results. An added benefit of using this shortcut is that it is compatible with Internet Explorer so you don’t need to make a separate XDR request.

$(document).ready(function() {
	loadLatestTweet();
});

function loadLatestTweet(){
	var _url = 'https://api.twitter.com/1/statuses/user_timeline/CypressNorth.json?callback=?&count=1';
	$.getJSON(_url,function(data){
		//data is holding a JSON object
	});
}

We now have the timeline back as JSON in the data object.

Building the HTML

Now that we have the status update, we need to display it somewhere. An easy way to do it is to create a <DIV> element with a unique ID for your twitter feed like so:

<div id="twitter-feed"></div>

Using jQuery, you can fill this div with the twitter response:

function loadLatestTweet(){
	var _url = 'https://api.twitter.com/1/statuses/user_timeline/CypressNorth.json?callback=?&count=1';
	$.getJSON(_url,function(data){
		var tweet = data[0].text;
		$("#twitter-feed").html('<p>'+tweet+'</p>');
	});
}

You have successfully retrieved your twitter status update and placed it on the page. The trouble is, it looks terrible and is pretty useless at the moment. Usually when you see a twitter post, it has links to the @Users and #hashtags mentioned in the posts and shows the date stamp of the update.

Parsing the Response

To make the status update more friendly and meaningful, we want to parse out any URL’s, @Usernames, and #Hashtags so that they are links. In addition we want to parse the date stamp of the update into a nice format which links to the original status update. To do that, we have a date parsing function and 3 JavaScript extensions to make our lives easier (thank you to Simon Whatley for the prototype extensions).

//Twitter Parsers
String.prototype.parseURL = function() {
	return this.replace(/[A-Za-z]+://[A-Za-z0-9-_]+.[A-Za-z0-9-_:%&~?/.=]+/g, function(url) {
		return url.link(url);
	});
};
String.prototype.parseUsername = function() {
	return this.replace(/[@]+[A-Za-z0-9-_]+/g, function(u) {
		var username = u.replace("@","")
		return u.link("http://twitter.com/"+username);
	});
};
String.prototype.parseHashtag = function() {
	return this.replace(/[#]+[A-Za-z0-9-_]+/g, function(t) {
		var tag = t.replace("#","%23")
		return t.link("http://search.twitter.com/search?q="+tag);
	});
};
function parseDate(str) {
    var v=str.split(' ');
    return new Date(Date.parse(v[1]+" "+v[2]+", "+v[5]+" "+v[3]+" UTC"));
}

Using these methods we can create a nice looking and helpful status update with ease:

function loadLatestTweet(){
	var _url = 'https://api.twitter.com/1/statuses/user_timeline/CypressNorth.json?callback=?&count=1';
	$.getJSON(_url,function(data){
		var tweet = data[0].text;
		var created = parseDate(data[0].created_at);
                var createdDate = created.getDate()+'-'+(created.getMonth()+1)+'-'+created.getFullYear()+' at '+created.getHours()+':'+created.getMinutes();
                tweet = tweet.parseURL().parseUsername().parseHashtag();
		tweet += '<div class="tweeter-info"><div class="uppercase bold"><a href="https://twitter.com/#!/CypressNorth" target="_blank" class="black">@CypressNorth</a></div><div class="right"><a href="https://twitter.com/#!/CypressNorth/status/'+data[0].id_str+'">'+createdDate+'</a></div></div>'
		$("#twitter-feed").html('<p>'+tweet+'</p>');
	});
}

*Note: The reason for the parseDate() function is to normalize the date format as it is not the same across browsers. If you skip that step it may fail in Internet Explorer (surprise).

Full Solution

Bringing it all together you have the full script ready for use, all you need to do is edit the HTML and CSS to suite your needs.

You can download the script and sample HTML file here: Twitter-Feed-Reader.zip

$(document).ready(function() {
	loadLatestTweet();
}); 

//Twitter Parsers
String.prototype.parseURL = function() {
	return this.replace(/[A-Za-z]+://[A-Za-z0-9-_]+.[A-Za-z0-9-_:%&~?/.=]+/g, function(url) {
		return url.link(url);
	});
};
String.prototype.parseUsername = function() {
	return this.replace(/[@]+[A-Za-z0-9-_]+/g, function(u) {
		var username = u.replace("@","")
		return u.link("http://twitter.com/"+username);
	});
};
String.prototype.parseHashtag = function() {
	return this.replace(/[#]+[A-Za-z0-9-_]+/g, function(t) {
		var tag = t.replace("#","%23")
		return t.link("http://search.twitter.com/search?q="+tag);
	});
};
function parseDate(str) {
    var v=str.split(' ');
    return new Date(Date.parse(v[1]+" "+v[2]+", "+v[5]+" "+v[3]+" UTC"));
} 

function loadLatestTweet(){
	var _url = 'https://api.twitter.com/1/statuses/user_timeline/CypressNorth.json?callback=?&count=1';
	$.getJSON(_url,function(data){
		var tweet = data[0].text;
                var created = parseDate(data[0].created_at);
                var createdDate = created.getDate()+'-'+(created.getMonth()+1)+'-'+created.getFullYear()+' at '+created.getHours()+':'+created.getMinutes();
                tweet = tweet.parseURL().parseUsername().parseHashtag();
		tweet += '<div class="tweeter-info"><div class="uppercase bold"><a href="https://twitter.com/#!/CypressNorth" target="_blank" class="black">@CypressNorth</a></div><div class="right"><a href="https://twitter.com/#!/CypressNorth/status/'+data[0].id_str+'">'+createdDate+'</a></div></div>'
		$("#twitter-feed").html('<p>'+tweet+'</p>');
	});
}

UPDATE API 1.1

To load more than just the latest tweet, modify the loadLatestTweet() function to look like the following (and change the count parameter to the number of tweets you want):

function loadLatestTweet(){
	var numTweets = 1;
    var _url = 'https://api.twitter.com/1/statuses/user_timeline/CypressNorth.json?callback=?&count='+numTweets+'&include_rts=1';
    $.getJSON(_url,function(data){
    for(var i = 0; i< data.length; i++){
            var tweet = data[i].text;
            var created = parseDate(data[i].created_at);
            var createdDate = created.getDate()+'-'+(created.getMonth()+1)+'-'+created.getFullYear()+' at '+created.getHours()+':'+created.getMinutes();
            tweet = tweet.parseURL().parseUsername().parseHashtag();
            tweet += '<div class="tweeter-info"><div class="uppercase bold"><a href="https://twitter.com/#!/CypressNorth" target="_blank" class="black">@CypressNorth</a></div><div class="right"><a href="https://twitter.com/#!/CypressNorth/status/'+data[i].id_str+'">'+createdDate+'</a></div></div>'
            $("#twitter-feed").append('<p>'+tweet+'</p>');
        }
    });
}