Using the Flickr API Explorer and Documentation

The column on the right at lists all the API methods available in the Flickr API. There are currently 106 methods in the API organized in the following 23 groups:

I’ve already used two methods in the early parts of the chapter: flickr.test.echo (part of the test group) and (part of the photos group). In this section, I’ll show you how to exercise a specific API method in detail and return to looking at the full range of methods. Here I use for an example.

You can get the documentation for any method here:{method-name}.html

For example:

Notice the following subsections in the documentation of each method:

In the documentation, there is a link to the Flickr API Explorer:{method-name}

For example:

The Flickr API Explorer is my favorite part of the Flickr API documentation. Figure 6-1 shows the API Explorer for For each method, the API Explorer not only documents the arguments but lets you fill in arguments and call the method (with your argument values) right within the browser. You have three choices for how to sign the call:

Figure 6.1. Figure 6-1.The Flickr API Explorer for (Reproduced with permission of Yahoo! Inc. ® 2007 by Yahoo! Inc. YAHOO! and the YAHOO! logo are trademarks of Yahoo! Inc.)

Figure 6-1.The Flickr API Explorer for (Reproduced with permission of Yahoo! Inc. ® 2007 by Yahoo! Inc. YAHOO! and the YAHOO! logo are trademarks of Yahoo! Inc.)

When you hit the Call Method button, the XML of the response is displayed in an iframe, and the URL for the call is displayed below the iframe. You can use the Flickr API Explorer to understand how a method works. In the case of the unsigned call, you can copy the URL and substitute your own API key to use it in your own programs.

For example, if you use the Flickr API Explorer to call with the tag set to puppy and then click the Do Not Sign Call button, you’ll get a URL similar to this:{api_key}&tags=puppy

Copy and paste the URL you get from the Flickr API Explorer into a web browser to convince yourself that in this case of searching for public images, you can now call the Flickr API through a simple URL that returns results to you in XML.


The Flickr API Explorer uses an api_key that keeps changing. But that’s fine because you’re supposed to use your own API key in your own applications. Substituting your own key is not hard for an unsigned call.

Now when I click Sign Call As Raymond Yee with Full Permissions, I get the following URL:{api_key}&tags=puppy&auth_token=72157601583650732-e30f91f3313b3d14&

When I use that URL immediately—before the key expires—I get to perform searches for puppy-tagged photos with write permission for my user account. This URL is useful to test the functionality of the method. It’s not so useful for dropping into a program. Getting it to work is not simply a matter of substituting your own api_key but also getting a new auth_token and calculating the appropriate api_sig (that is, signing the call)—tasks that take a couple of more calls to the Flickr API and a bit of computing. It’s this set of calculations, which makes authorization one of the trickiest parts of the Flickr API, that I will show you how to do later in the chapter.