How to Use JSON APIs with jQuery

One of the best features of jQuery is its simple AJAX functionality. This allows you to easily pull data from other sites and services onto your own site. Learning how to use this functionality makes it easy to integrate any number of services into your websites, making them richer and more interesting to your visitors. It will also make you less dependent on the widgets that companies provide, allowing you to create your own.

For this post, I am going to show how I created URL Tweet Compete, a tool that allows you to enter multiple urls into a textarea, and it then returns the number of tweets that the they have on Twitter. Be sure to try it out so that you can understand what this post is all about.

The tools uses the Topsy Otter API. This is a fun API to play around with because it is easy to understand and it doesn't require any authentication.  Additionally, it supports jsonp which is important as I will explain later.

The core call in jQuery for this project looks like this:

$.ajax({
    url: "http://otter.topsy.com/urlinfo.js?url=http://www.nytimes.com",
    dataType: 'jsonp',
    success: function(results){
        console.log(results);
    }
});

Now lets get in to the mechanics of how this works.

What are APIs? What is AJAX?

This might be old news, but it's worth covering quickly. You could read all day about APIs and AJAX, but they are also easy enough to understand in concept.

An API is a tool that makes information available to progams in a more convenient format.  As an example, humans can go to Twitter's website in their browser to see a pretty display of tweets.  The Twitter API however presents the tweets in a way that is convenient for programs.  It just gives the info.

AJAX is a phrase that roughly means "fetching information on a loaded page using Javascript".  It is an acronym with a specific meaning, but it is now used more generally.  The "X", for example, stands for XML, but now AJAX is used whenever there is any kind of dynamic content is being displayed, including JSON. Typically, AJAX is used in conjunction with an API.

So how does it work?

In the example above we are initializing an AJAX request to the Topsy API. You can see exactly what happens by checking out the URL yourself, directly: http://otter.topsy.com/urlinfo.js?url=http://www.nytimes.com As you can see, the following is shown:

So when that request is made, some data is sent back. We're now able to use this data however we like on the page.  In the case of the URL Tweet Compete app, we're displaying the "trackback_total" value which represents the total number of tweets that have been received.

What is JSONP?

When making AJAX requests to external domains, there are a number of restrictions that apply for security reasons. JSONP is a technique to get around these restrictions. jQuery builds it into their $.ajax() method to make it easy to use.

Whenever you're using an API that is hosted on another domain, you'll need to make sure you're using the jsonp version of the API. Topsy offers an XML, JSON and JSONP version. A common mistake is attempting to use the JSON version which is impossible with javascript on another domain.

With Topsy (and many other APIs), you can select which version you want by changing the extension on your request.  For the XML version, use ".xml", for the JSON version use ".json".  Usually to get the jsonp version, you'll use either ".jsonp" or ".js".

Putting it All Together

So in order to request information from the Topsy API and display it on a page, you'll need some code like this:

$.ajax({
    url: "http://otter.topsy.com/urlinfo.js?url=http://www.nytimes.com",
    dataType: 'jsonp',
    success: function(results){
        var title = results.response.oneforty;
        var numTweets = results.response.trackback_total;
        $('#results').append(title + ' has ' + numTweets + ' tweets.');
    }
});

This code goes and fetches information about the url: http://www.nytimes.com and then displays the number of tweets it has.  Notice that we're doing the displaying within the 'success' function.  This is because we don't get the information back from our Topysy AJAX request immediately.

Instead, once it comes back, jQuery calls the success function that we define and passes in the results so that we can use them.

Hopefully this post is helpful for those new to using APIs and AJAX.  If there are any questions or comments, please leave them below!