Final Result Preview
Let’s take a look at the final result we will be working towards:
All major web sites these days offer an API to give developers access to their service. While there are some standards in place (like OpenSocial, OAuth etc) for the most part each web site exposes their service in their own unique way. This is a major headache for developers, who have to learn a new set of classes and functions for every site they work with.
Step 1 – Creating the YQL query
Before we start writing any code, lets take a look at how we use the YQL service.
The syntax used to access the YQL service is very similar to SQL. The YQL Console is a tool that lets you craft and test these queries before committing them to your code.
Open up the YQL Console in your browser. The Data Tables panel, in the bottom right hand corner, shows all the tables that YQL can access. Expand the twitter item and click on the twitter.user.status link. If the twitter item is not available, click the Show Community Tables link.
Almost all YQL tables include a sample YQL query. In this case we get the query select * from twitter.user.status where id=’bartt’. Anyone familiar with SQL should instantly recognize the format of the query.
The YQL Console provide two other important functions. The first is that it provides the URL that needs to be called, complete with all the required parameters, to execute the query from our code.
This application will actually make use of the twitter.user.timeline table. This is because the twitter.user.status table does not include the twitter users profile image. The link for the twitter.user.timeline table in the YQL Console does not have a sample query, instead returning the default query desc twitter.user.timeline, which returns the details of the table itself rather than running a query on the data the tables holds. However we can query the twitter.user.timeline table just like the twitter.user.status table with select * from twitter.user.timeline where id=’mcasperson’.
Step 2 – Create a basic HTML document
With the YQL URL in hand, we now need to write some code. To demonstrate this application we first need a simple HTML file. The code below shows the outline of the HTML document.
Step 3 – Add a link to jQuery
For convenience we will use the jQuery library, which allows us to easily modify the HTML elements, as well as call the YQL service. You can get a copy of jQuery for yourself here. The following code, added in the tag, includes the jQuery code in our page.
Step 4 – Update the page when it is first displayed
Step 4 – Calling the YQL service
The queryYQL function is where we actually call the YQL service and then display the results. In step 1 we obtained a copy of the URL that will query a users twitter status from YQL. You could copy that straight into your code without any problem (as long as you set the callback function to ? instead of the default cbfunc – this will be explained below). However, for this application we want to be able to specify whose Twitter account we will query. To achieve this we build up the final URL in a number of steps.
var yqlUrl = “http://query.yahooapis.com/v1/public/yql”;
The yqlUrl variable holds the base URL for the YQL service.
var query = “select * from twitter.user.timeline where id='” +
document.getElementById(‘twittername’).value + “‘”;
We then build up the YQL query, obtaining the user name from a HTML input element (which will be added in later steps).
var queryUrl = yqlUrl + “?q=” + escape(query) + “&format=json&callback=?” + “&env=” + escape(“store://datatables.org/alltableswithkeys”);
The reason why the callback function is specified as a question mark is because jQuery will replace the question mark with a reference to the function passed into the getJSON function as the second parameter. You can find out more information the getJSON function here.
$(“#twitterstatus”).text(“Loading Twitter Status…”);
Before we contact the YQL servers, we first hide the image and display the message “Loading Twitter Status…”.
$.getJSON(queryUrl, function (yqlObject)
This URL is then passed to the jQuery getJSON function, which will contact the YQL server and pass the JSON object that has been returned to a function supplied as the second parameter.
var twitterText = yqlObject.query.results.entry.title.replace(
document.getElementById(‘twittername’).value + “: “, “”);
The status updates are all prefixed with the twitter user name, like “mcasperson: this is my twitter status”. This leading user name is redundant (or at least better displayed elsewhere), so we use the string replace function to get a copy of the latest twitter status post where the user name has been removed.
To display the twitter status we update the element with an ID of twitterstatus with the last status update, and update an IMG element with the ID of twitterimage with the twitter users profile picture. We also set the IMG element to be visible. All of these HTML elements will be created in later steps.
In order to make the twitter status dynamic, we schedule the queryYQL function to be called again in 60 seconds (or 60000 milliseconds) using the setTimeout function.
Step 5 – Creating the rest of the HTML
Step 6 – Some considerations
Twitter limits the number of calls that can be made to their service to 150 per hour for public (i.e. no user authentication required) REST calls. This may impact on how often you want a web page to update the twitter status – 2 pages using the code above left open for an hour would make 120 calls in that time. It’s also worth noting that you are competing for API calls with other Twitter applications the client may have running like TweetDeck. If the twitter account you are watching does not update very often it would be worthwhile increasing the time given to the setTimeout function.
This is not just an issue with Twitter: all services exposed by YQL may be subject to rate limits imposed by the underlying service. It’s always best to check for these limits when using YQL.
YQL is a powerful service that exposes hundreds of otherwise unrelated web services through a single, unified syntax and API. It will make your applications faster and decrease your development time. Whether you are using one web service, or creating a mashup the involves several, YQL will make your life as a web developer a little easier.
Download the source code here.