Flickr

Flickr has fast become the site to host images; its easy-to-use feature set combined with easy-to-use web elements to drop photos on blogs or homepages has made it a big hit. Andy Ihnatko of the Chicago Sun Times probably said it best:

Note 

There are already way too many websites out there where you can upload and display your digital photos, and on the whole, watching these services develop is like watching cavemen trying to figure out fire.

But the folks who've created www.Flickr.com get it. They got it, and then they went and beat up some kid on the playground and they took his stuff, too.

Strong praise, but they deserve it.

One of the API's most attractive options is that it gives you access to all of the (public) images within the archives, rather than just your own. This would allow (for example) a site about horticulture to randomly display images from within the Flickr database that have a particular keyword such as flower (being careful, of course, to credit the images). Though the process of randomly displaying images from the Flickr system is the focus of this brief introduction, the API itself is quite powerful — entire image management applications can be (and have been) built using the Flickr backend.

As seems to be a growing trend, the Flickr API offers both a SOAP and a REST interface; for this section the REST interface is used. The actions performed in this section are all "safe" in that they don't request any changes in Flickr's database, so I am comfortable with this approach.

Obtaining an API Key

Obtaining an API key is relatively easy; it's even an automated process if you are requesting a key for noncommercial use. Once you have logged in to your Flickr account, head to www.flickr.com/services/api/ (it can be a bit tricky to find via the site's regular navigation; it's listed under the complete sitemap link, toward the bottom). Click the API Keys link, then the application link. You will need to enter a brief description of the application you are planning to build, and you're off to the races.

Determining Your User ID

Flickr associates a user id with every user. This is not the same as the username used to log in to the system. A user id is required to restrict searches to images from a particular user and it's also a very simple query. Here is the request URL:

 http://www.flickr.com/services/rest/?method=flickr.people.findByUsername&api_key=13   cff9127a1ceb6da54bd2d21e25d1aa&username=preinheimer 

Flickr's response looks like this:

 <?xml version="1.0" encoding="utf-8" ?> <rsp stat="ok">  <user  ns>       <username>preinheimer</username>  </user> </rsp> 

Although both id and nsid are the same in this case, the API's documentation indicates that the nsid is the value you want to record. The code used to generate this request and show the response is as follows:

 <?php $endPoint = "http://www.flickr.com/services/rest/?"; $parameters = array(); $parameters[] = array("method", "flickr.people.findByUsername"); $parameters[] = array("api_key", "13cff9127a1ceb6da54bd2d21e25d1aa"); $parameters[] = array("username", "preinheimer"); foreach ($parameters AS $parameter) {  $endPoint .= $parameter[0] . "=" . $parameter[1] . "&"; } $response = file_get_contents($endPoint); $xml = simplexml_load_string($response); echo $response; $nsid = $xml->user[‘nsid']; ?> 

The call's endpoint is given by the API; the parameters change depending on the specific request. The various parameters are saved into an array before being combined to form the final endpoint. There are other ways to accomplish this (the entire URL could just be hard coded, for example), but using this framework should make calling a new method quick and easy. After the endpoint is set, the response document is retrieved and parsed into a SimpleXML object. Finally, the nsid is recorded for possible later use.

Retrieving Images from a Particular User

With the nsid in hand, retrieving images from a particular user is relatively easy:

 $parameters = array(); $endPoint = "http://www.flickr.com/services/rest/?"; $parameters[] = array("method", "flickr.photos.search"); $parameters[] = array("api_key", "13cff9127a1ceb6da54bd2d21e25d1aa"); $parameters[] = array("user_id", "77964564@N00"); foreach ($parameters AS $parameter) {  $endPoint .= $parameter[0] . "=" . $parameter[1] . "&"; } $response = file_get_contents($endPoint); $xml = simplexml_load_string($response); 

This request yields the following (some of the responses have been trimmed for size):

 <rsp stat="ok">   <photos page="1" pages="1" perpage="100" total="29">     <photo  owner="77964564@N00" secret="3e5b05764b" server="6"       title="DCP_0877" ispublic="1" isfriend="1" isfamily="1" />     <photo  owner="77964564@N00" secret="0b35b20599" server="5"       title="ForbiddenLove" ispublic="1" isfriend="1" isfamily="1" />     <photo  owner="77964564@N00" secret="67ec4565e6" server="5"       title="Elegance of Three" ispublic="1" isfriend="1" isfamily="1" />     <photo  owner="77964564@N00" secret="c610053f55" server="4"       title="WitheringBeauty" ispublic="1" isfriend="1" isfamily="1" />     <photo  owner="77964564@N00" secret="e7b93a7ef4" server="3"       title="Pink" ispublic="1" isfriend="1" isfamily="1" />   </photos> </rsp> 

As you can see, you get some information about each of the images applicable to the search. Some of the information provided, like title or id, is pretty self-explanatory, whereas the other information is a bit more arcane. Owner is the nsid of the owner of the image. Because all of the images are owned by the same person (that was the search performed), these will match all the way through. The secret value is required if you want to retrieve the particular image, and it can also be used to give a link to a private image. The server indicates which machine the image resides on. This information will be used to generate a link to the image in question. ispublic, isfriend, and isfamily are all binary values stating the permissions of the image: 1 = has access, 0 = does not have access.

Turning Image Information into a URL

Suspiciously absent from the image information is a URL from which the image can be retrieved or viewed. The information given, however, is sufficient to generate the URLs. The form for any URL is as follows:

 http://static.flickr.com/{server-id}/{id}_{secret}_[stmbo].jpg 

The server-id, id , and secret values map perfectly to the values returned by the API. The last options [smstbo] are used to indicate the desired size of the image:

• s — Small square, 75×75px

• t — Thumbnail, 100px on the longest side. The other side will be scaled appropriately.

• m — Small, 240px on the longest side. The other side will be scaled appropriately.

• b — Large, 1,024px on the longest side. This will only be available when the source image is sufficiently large. The other side will be scaled appropriately.

• o — Original. The original image, whatever size it is. You must use the appropriate file extension for the image (jpg|png|gif).

Note 

Note that when using the t, m, b , or o image sizes, the resultant image may or may not be square. It will be a proportionally sized image with the longest side being the indicated length.

Putting It Together

Putting what you know about image URLs together with the information received from the API, you can start sending image tags to the browser:

 foreach($xml->photos->photo as $photo) {   echo "<img src=\"http://static.flickr.com/{$photo[‘server']}/{$photo[‘id']}_     {$photo[‘secret']}_m.jpg\"><br>\n"; } 

This comes out looking like the image in Figure 11-2.

Figure 11-2

Alternatively, for a more visually appealing display of graphics, adding in just a bit of styling, you can get something as shown in Figure 11-3. Here is the code:

 echo "<img src=\"http://static.flickr.com/{$photo[‘server']}/{$photo[‘id']}_ {$photo[‘secret']}_m.jpg\" style=\"float: left; display: table-cell; width:   240px; height: 240px; text-align: center; vertical-align: middle;\">\n"; 

Figure 11-3

Finding Images by Tag

Flickr's system allows users to associate multiple tags with their images. This is a relatively loose system — not all users associate tags with their images, nor is there any required structure for the tags. That being said, the system is large enough that running a search for tags like "flower", "rose", or "puppy" is going to yield many results. Changing the script to search by tags only requires a few changes to the parameters given:

 $parameters = array(); $parameters[] = array("method", "flickr.photos.search"); $parameters[] = array("api_key", "13cff9127a1ceb6da54bd2d21e25d1aa"); $parameters[] = array("tags", "flower"); 

This returns a number of images that have the tag "flower" associated with them.

Restricting Your Search by License

Flickr also allows users to specify a Creative Commons license (http://creativecommons.org/) to distribute their images under. When performing a search, you can restrict your search to images distributed under a specific license. The applicable licenses are as follows:

• 0 — None (All rights reserved)

• 1 — Attribution, noncommercial, share alike

• 2 — Attribution, noncommercial

• 3 — Attribution, noncommercial, no derivatives

• 4 — Attribution license

• 5 — Share-alike license

• 6 — Attribution, no derivatives

So to perform a search, restricting it to a particular license, just add license as a parameter:

 $parameters[] = array("license", "2"); 

This will only return images licensed under the Attribution, noncommercial license.

Flickering Conclusion

The Flickr library is very extensive, containing images posted by users from around the globe. Even though only a percentage of users bother to tag their images with keywords, running a search for most words yields a plethora of results. The ability of users to associate licenses with their images, combined with the ability of the API to filter based on that information, can provide a wealth of images to be used in personal projects, or for dynamic displays on themed websites.