IntroductionFlickr is an image hosting and video hosting website, web services suite, and online community that was created by Ludicorp in 2004 and acquired by Yahoo! in 2005. Flickr offers a fairly comprehensive web-service API that enables programmers to create applications that can perform almost any function that a user on the Flickr site can do. The Glickr plugin aims to provide (as time passes) a feature complete implementation of the Flickr API by providing a Grails service and native Groovy classes that wrap the API. So rather than having to deal with individual and Flickr specific API methods, the Glickr Plugin wraps API calls in native classes and provides typical Grails methods like '.getByUsername()' or '.findAll()'
InstallationInstallation is pretty straight-forward, since the plugin currently has no further dependencies, you start the command prompt and type:
grails install-plugin glickrAlternatively, you can download the Glickr Plugin manually from the Grails website
ConfigurationTo work with the Flickr API, you need an API Key that can be requested at Flickr website. Put the information provided by Flickr in the following entries in your Grails configuration file (e.g. Config.groovy):
grails.plugins.glickr.apiKey = 'YOUR_FLICKR_API_KEY' grails.plugins.glickr.apiSecret = 'YOUR_FLICKR_API_SECRET'
After succesfully installing the Glickr Plugin in your Grails project, you'll have a service available to interact with the Flickr API:
Getting StartedThe examples below might be a bit verbose (un-Groovy) but it'll help to understand what the service does for you and what Groovy classes are available.
FlickrPeople people = flickrService.getPeopleById('86869926@N02')
The will result in one of 3 scenarios:
- A user (called People in Flickr API jargon) with provided ID is found and returned as an instantiated object of class FlickrPeople
- A NULL object is returned when no user with the provided ID is found
- In any other scenario, something is wrong with the configuration, the syntax or even the actual Flickr server. In that case an exception of type FlickrServiceException will be thrown. For more information on possible exceptions and how to deal with them; please read this blogpost.
Several other methods of getting a FlickrPeople object are:
FlickrPeople people = flickrService.getPeopleByUsername('glickr.org') FlickrPeople people = flickrService.getPeopleByEmail('firstname.lastname@example.org')
But the most important thing on Flickr are of course images, so let's look at a couple of example how to find and deal with photos.
FlickrPhoto photo = flickrService.getPhotoById(7955082398)Well, you'll get the picture (pun intended), or a NULL object, or a flavor of FlickrServiceException. While the previous examples returns an object of the class FlickrPhoto, it is a pretty empty object to begin with, just some basic metadata and URL to link back to Flickr.
A photo hosted on Flickr can have lots of additional information, metadata, or geo-data and can be retrieved in multiple sizes (depending on what the was uploaded and provided by the owner of the photo). In order to 'decorate' a FlickrPhoto with more data you can call 'getPhotoDetails' to have fill all attributes:
FlickrPhoto photo = flickrService.getPhotoById(7955082398) photo = flickrService.getPhotoDetails(photo) println photo.shortUrl println photo.title println photo.sourceWidth println photo.sourceHeight println photo.sourceUrlClearly, the former method 'getPhotoById' is much faster, specially since the latter 'getPhotoDetails' will execute multiple individual calls to the Flickr API in order to collect all metadata. There's also a tag for easier HTML rendering of a FlickrPhoto object:
Just like there is a tag for easier rendering of a FlickrPeople object: There's also a tag for easier rendering of a FlickrPhoto object to HTML
From a FlickrPeople object you can also get a set of public FlickrImage objects that are published by this 'user':
FlickrPeople people = flickrService.getPeopleByUsername('glickr.org') FlickrPhotoSet photos = flickrService.getPeoplePublicPhotos(people)Several different signatures for the same functionality:
def photos = flickrService.getPeoplePublicPhotosById('86869926@N02') def photos = flickrService.getPeoplePublicPhotosByUsername('glickr.org') def photos = flickrService.getPeoplePublicPhotosByEmail('email@example.com')The most versatile function to retrieve images is the Search function of the Flickr API, implemented in the flickService as 'findAll()'. For the initial release of the Glickr Plugin, we implemented about 50% of the possibilities of this method. First, a straightforward find all images that are associated with a text (i.e. the text appears in the title or description of the image).
FlickrPhotoSet photos = flickrService.findAll([text='sp91052'])Or provide some additional parameters, to browse to bigger result sets:
FlickrPhotoSet photos = flickrService.findAll([text='PCD0992', page=1, perPage=10])The Glickr Plugin also provides for a couple of Enums to handle additional options for the search function. Different scenarios are show in the example below while searching in the 'tags' of images on Flickr:
// example def params FlickrPhotoSet photos // search on one tag params = [tags:'GlickrTest'] photos = flickrService.findAll(params) // search on multiple tags, defaults to 'Any' match params = [tags:'GlickrTest,Horizontal'] photos = flickrService.findAll(params) // search on multiple tags, make 'Any' explicit by using the TagMode Enum params = [tags:'GlickrTest,Horizontal',tagMode:TagMode.Any] photos = flickrService.findAll(params) // search on multiple tags, result meets all tags params = [tags:'GlickrTest,Horizontal',tagMode:TagMode.All] photos = flickrService.findAll(params)Similarly, there is an Enum to specify the types of content to return
// example def params FlickrPhotoSet photos // ContentType.All is the default value params = [text:'PCD0992',contentType: ContentType.All] // default photos = flickrService.findAll(params) // or params = [text:'PCD0992',contentType: ContentType.Photos] params = [text:'PCD0992',contentType: ContentType.Screenshots] params = [text:'PCD0992',contentType: ContentType.Other] params = [text:'PCD0992',contentType: ContentType.PhotosAndScreenshots] params = [text:'PCD0992',contentType: ContentType.ScreenshotsAndOther] params = [text:'PCD0992',contentType: ContentType.PhotosAndOther]