HOWTO: build a Technorati top tags ticker with PHP, jQuery, JavaScript and AJAX - day 1 of 3

The “how to” I posted on sprucing up your search box with CSS and a background image received some great feedback. I have decided to follow up with a more in depth tutorial that takes advantage of the Technorati developer’s API, specifically, the ability to retrieve the current top tags. Over the next three days I will teach you how to build an imitation of the tags ticker running at the top of the Technorati home page, using PHP, jQuery, JavaScript and AJAX.

I would consider this an intermediate to advanced tutorial, so feel free to ask questions along the way. The JavaScript and CSS have a fair bit of meat to them, and the jQuery snippets are a good introduction to the framework. You will not be at a disadvantage if you lack expert PHP knowledge. The four lines required to request an XML file from Technorati is robust enough to do the job, but simple enough for beginners to grasp. It will certainly wet your appetite for more PHP in the future.

Day 1: An introduction to the Technorati API, the PHP, and the ticker

Several social networking and decision making sites offer an API so that you can tap into the vast amounts of information submitted primarily by users. The most popular recently has been Facebook’s, but Digg, Twitter, Technorati, and numerous others release data to developers. The only requirement is that you attribute that data to the source, and that you be a registered member. As a reminder, remember to credit Technorati if you do use the ticker in a production environment, and be sure to read the terms of use.

The Technorati API relies on a REST-ful interface, which stands for Representational State Transfer. Loosely defined, you get access to data on another domain over HTTP without a messenger in between. In this particular instance, instead of dealing with services (and validation), you get the goods immediately. This can have security implications, but I will not address those in this post, and it will be assumed that we can trust the XML data as outlined by Technorati’s developer documentation.

According to Technorati, you can make 500 API calls in a day free of charge. Your queries are tracked in your account so that you know when you are reaching the limit. Depending on the API, and how important it is that the information be recent, you may wish to cache the data in an object on the server. Instead of making an API call for every user, you can call the object. If you receive a spike in traffic, this will prevent your widget from failing. Another alternative would be to save a copy of the XML to your own server, and then retrieve this document with each call.

To grab the top tags, send an HTTP GET, or HTTP POST to the domain provided by Technorati. I will use PHP to accomplish this, but you can also use Java, .NET and Ruby on Rails.

XHTML:

http://api.technorati.com/toptags?key=[apikey]

The apikey value in the key query string variable should be replaced with your developer API key (without the brackets), which you can get by registering with Technorati. This is the only mandatory variable, and it will output 20 top tags in XML, including the number of posts associated with each particular tag. The optional variables are format, limit, and start, which you can read more about on Technorati’s Web site. The XML below is a condensed sample.

XML:

<?xml version="1.0" encoding="utf-8"?>
<!-- generator="Technorati API version 1.0 /topptags" -->
<!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN" "http://api.technorati.com/dtd/tapi-002.xml">
<tapi version="1.0">
    <document>
        <result>
            <limit>20</limit>
        </result>
        <item>
            <tag>Weblog</tag>
            <posts>7874061</posts>
        </item>
        <item>
            <tag>Life</tag>
            <posts>6463753</posts>
        </item>
        ...
    </document>
</tapi>

PHP has a powerful library extension called cURL, or Client URL, which I will use to request this XML. With the assistance of cURL you can scrape the contents of an entire Web site, or provide directory listings based upon open standards like DMOZ. The possibilities are quite endless, and this implementation is only the tip of the iceberg. Again, there are always security risks. So, before you go grabbing URLs unhinged, think of what might happen if you siphoned content from a Web site that has been hijacked and injected with malicious code.

PHP:

header ("content-type: text/xml")
$ch = curl_init('http://api.technorati.com/toptags?key=[apikey]')
curl_exec($ch)
curl_close($ch)

Not too shabby, is it?

Upon execution, cURL posted to the URL provided, and then spit back the response to the browser. If you were to browse to a PHP page served up with this code, the browser would show you XML. In case you are wondering, the header tag is a requirement. The user agent understands that this is an XML document, but the AJAX component will not understand the object type if the appropriate mime (content) type is absent. Go ahead and give it a try. It really is that easy.

So without further ado, it is time to unveil the interface for the top tags ticker. This is not an exact duplicate of Technorati’s ticker, but the similarities are obviously apparent by the screenshots. As an aside, the jQuery and JavaScript in this tutorial are coded from scratch. It was important that the final product be built to suit the needs of many, as opposed to the Technorati ticker, which was built with that particular Web site’s needs in mind.

[Screenshot of the Technorati ticker.]

[Screenshot of the top tags imitation ticker.]

Tomorrow I will provide a walkthrough of the XHTML and CSS required to display the ticker, and on day three I will finish up with the jQuery, JavaScript and AJAX portion of the tutorial. Now that the foundation has been set, you can look forward to wading through the wealth of code yet to come.

• Posted by Brian
• August 21st, 2007