How to get started with the Tumblr API, part 1

Every well known service on the Web has an API we can play with to get its data feed and Tumblr is no exception; the popular blogging platform has a really intuitive API that we can use to get anything from avatars to posts with links and images.

In this article I’ll give you a feel for this API and teach you how to make some simple requests.

Getting an API key

If you’re familiar with working with this kind of API, you’ll know that we usually need to create and application and request an API key in order to perform requests; Tumblr is no exception.

To register your application you can simply head here and create a new one. It will ask you some simple questions (the Google Play URL and App Store URL are not required) and you will be redirected to a page where you can see your OAuth consumer key. Save that key, because that’s all we will need.

Performing requests

Let’s start with something basic: we’ll retrieve a Tumblr blog info together with its avatar. The reason these requests are simple is the relatively small json response that Tumblr returns.

The first thing we need to know is the URL to make the call to. For blog information we need the following URL. (Don’t forget to replace your-api-key with your API key!)

http://api.tumblr.com/v2/blog/blog.tumblr.com/info?api_key=your-api-key

We need to make a get request, which we can do with a simple ajax call to the URL, like so:

$.ajax({
    url: "http://api.tumblr.com/v2/blog/blog.tumblr.com/info?api_key=your-api-key",
    dataType: 'jsonp',
    success: function(info){
      // Print Title On the Page
    }
});

This is a simple jQuery ajax call. The only thing to note is that the dataType is set to jsonp because we’re loading data from another domain.

If you add console.log(info); to the function you’ll see that we’re retrieved an object. The object has the data we’re after, so for example if we wanted to add the title to an h1 element we’d use code inside the function something like this:

$("h1").html(info.response.blog.title);

Retrieving the avatar for the Tumblr blog uses a similarly simple process; the URL that we start with is:

http://api.tumblr.com/v2/blog/blog.tumblr.com/avatar/<size>?api_key=your-api-key

(Again, make sure you replace your-api-key with your actual API key.)

As you can see, there’s a parameter in the URL. We need to replace that with our chosen size. The options are 16, 24, 30, 40, 48, 64, 96, 128 and 512—if you omit the parameter, you’ll get the default size which is 64×64.

Next, we perform a simple ajax jQuery call:

$.ajax({
    url: "http://api.tumblr.com/v2/blog/blog.tumblr.com/avatar/128?api_key=your-api-key",
    dataType: 'jsonp',
    success: function(avatar){
  $(".avatar").attr('src', avatar.response.avatar_url); 
    }
});

This call is very simple to the call we made to get the blog’s information. This time, we’re adding the data as the source of an image, rather than the text.

Next time

In the next post we’ll be retrieving full posts from Tumblr.