Using the Flickr API: We Don’t Need No Stinkin’ Badges

Earlier this week Flickr posted on their blog that the three billionth photo had been uploaded, so I thought this would be the perfect time to promote Flickr's services some more. A while back I wrote about pulling Flickr images using jQuery, but in that example we were using feeds provided by Flickr's services. Feeds are great because they don't require an API key, and with response formats like JSON, its become relatively easy to parse out the information coming in. The downside is that you can only work with the information within the feed you're pulling. Plus, that post was mostly about using jQuery and may have been a little much for most people who just want to simply pull images from Flickr. In this post, I'll show you how to easily use the Flickr API to display pictures on your site.

The Easy Way

Flickr offers a free badge creator because anyone with a Flickr account wants to show off pictures on their website. After answering some questions about how you want your badge to look, you get a tailored JavaScript include that you can just paste into your HTML and have pictures display on your page. This is really easy for anyone that just wants to show a couple photos on their blog, but doesn't feel like learning about the API (which as you'll see later is super easy). For example, here is what a personal badge (from Flickr user "vigetinspire") might look like:

<script type="text/javascript" src="http://www.flickr.com/badge_code_v2.gne? count=5&source=user&user=24878717@N06"></script> 

Or, if you want to pull random photos from a group (for example, Viget Inspiration Group Pool) and you wanted them to be sized in small equal boxes, it would look like this:

<script type="text/javascript" src="http://www.flickr.com/badge_code_v2.gne? count=5&source=group&group=675729%40N22&display=random&size=s"></script> 

You can also edit the JavaScript include parameters at any time to change what photos are pulled. The parameters are placed after "http://www.flickr.com/badge_code_v2.gne?". For example, "source=user" is a parameter, and tells Flickr "we're going to pull images from a user." Of course, you then have to tell Flickr what user you want to pull from, and that is why we put "user=24878717@N06". Go ahead an try putting in the JavaScript code into the body of a HTML webpage and try out some of the other parameters listed below (making sure you separate each one with "&"):

So you're probably thinking "This is good enough, I don't need to mess with Flickr's crazy API, this thing does everything!" It's true that the badges have the capabilities that the majority of people need (which is probably why Flickr put them in there) but it doesn't do "everything." The Flickr API gives you access to a ton of other information that the badge doesn't. Some of the stuff could even be considered overkill, but why not right? Aside from the vast amount of information on Flickr you have access to, you also have more control with the API. For example, the badges forces you to use Flickr's markup and it only pulls a max of 10 images (you can only set "count" equal to 1-10).

Badges? We don't need no stinkin' badges!

Many sites offer API's but most people still don't really get how to use them. Flickr's API is a great place to start since there is so much content, documentation, and a large community using it if you have questions. The first thing you'll need to do, like most API's, is request an API Key (which is just a unique code specific to your Flickr account). Flickr will check for this key in your code when you hit them up for information. Once you have your API Key, you can go to the Flickr services page for all the API documentation.

On the website we did for musician Martin Sexton, we wanted to display all the photos that were tagged with his name on Flickr, so that his fans could post photos. First, we need to use what is called a "request format" which is what will be used to tell Flickr what images we want. Flickr has the REST request format which sits at http://api.flickr.com/services/rest/ on Flickr's server. So if we send a "request" to Flickr, we need to tell Flickr what "response format" we want back. For this example, the response I will be using the JSON response format.

The Flickr API Request

The Flickr API is made up of a bunch of useful tools called "methods" which is what you use to request information from Flickr. One useful method is flickr.photos.search which has the parameters that most people can use to pull their photos. So if we wanted to pull all the pictures on Flickr that are tagged with "martin" and "sexton" we would place this piece of JavaScript into the body of our webpage page where we want it to display:

<script type="text/javascript" language="javascript" src="http://api.flickr.com/services/rest/?format=json&method=flickr.photos.search&tags=viget&tag_mode=all&api_key=[your API Key goes here]"></script>

As you can see, the script links to the the REST request, uses the API method "flickr.photos.search" to search for all photos with the tags "viget", and then tells Flickr that we want a JSON formatted response. The "api_key" parameter needs to be present in any request to the Flickr API to tell Flickr you're allowed to be doing all of this in the first place. Go check out all the other cool methods that are available in flickr.photos.search along with all the other methods!

The Flickr API Response

Just putting in that JavaScript into the body of the webpage isn't going to make it work. The reason is that Flickr is sending us back info in the JSON format NOT pretty HTML. So we need to put in JavaScript to turn the JSON code into markup that looks nice. For example, you can use the following JavaScript function which takes the JSON response and turns it into a bunch of linked images in HTML:

function jsonFlickrApi(rsp) {
 if (rsp.stat != "ok"){
 // If this executes, something broke!
 return;
 }
 
 //variable "s" is going to contain 
 //all the markup that is generated by the loop below
 var s = "";
 
 //this loop runs through every item and creates HTML 
 for (var i=0; i < rsp.photos.photo.length; i++) {
 photo = rsp.photos.photo[ i ];
 
 //notice that "t.jpg" is where you change the
 //size of the image
  t_url = "http://farm" + photo.farm + 
 ".static.flickr.com/" + photo.server + "/" + 
 photo.id + "_" + photo.secret + "_" + "t.jpg";
 
 p_url = "http://www.flickr.com/photos/" + 
 photo.owner + "/" + photo.id;
 
 s += '<a href="' + p_url + '">' + '<img alt="'+ 
 photo.title + '"src="' + t_url + '"/>' + '</a>';
 }

 document.writeln(s); 
 //this tells the JavaScript to write 
 //everything in variable "s" onto the page
}

Unlike the badges, I have total control over what markup goes on my page. Also, I am setting the size of the images I want in the JavaScript where we put "t.jpg" in the URL to the photo. This is because the "flickr.photos.search" method is just returning photo information but not restricting its size (the flickr.photos.search method doesn't even have the ability to set a size). But this brings up another benefit to using the API; you can access all sizes of photos that sit on Flickr's server. So in our JavaScript you could replace "t" with "s" for small, "m" for medium, or even "o" for original (which are large and sometimes doesn't show up).

You can do a lot of different a lot of different things with the Flickr API, and I encourage everyone to explore the documentation, as well as other API's, to learn how to use large amounts amounts of data more efficiently. Please share any other tips or suggestions about using the Flickr API, I'd like to hear about them.

EXAMPLES!

Remember that you can view the source to see how it's working

Using Flickr's badge

Using the Flickr API (Currently this isn't working because I haven't received a commercial API key from Flickr, but you can use the source code and replace [API Key] with your own key)