Flickr API Search Package for Umbraco

A recent ProWorks project had a need to pull Flickr photos from their community to display on their web site. I had never played with the Flickr API so I thought: “cool!”. I couldn’t find a Flickr Umbraco plugin on our.umbraco.org so I dug in and did it myself.

Thank goodness I found the Flickr.Net API Library. That nice little library took a daunting (or at least time consuming) task and made it fun. Also, the Flickr API Explorer for the flickr.photos.search method was very nice for testing.

On to the package…

Download ProWorks Flickr API XSLT Search 2.0 (58 KB) - Tested in Umbraco 4.0.x and 4.5

The package mainly consists of an XSLT extension called ProWorks.FlickrXSLTSearch. This extension has six methods of searching for and returning photos from Flickr: ByUser, ByGroup, ByFreeText, BySet, ByTag and ByUserAndTag.  In addition there are versions of each that support paging using Flickr API calls.

In addition, there is a sample XSLT and two data types to help let your users choose the search in a content page. The data types are the “sort mode” and “tag mode” selections options available in the Flickr photo search method.

How To Install:

1. Install the package from the “Packages/Install local package” item in the “Developer” section in the Umbraco Admin area. (Normal package install)

2. Get a Flickr API key for your website

To get a key go to this page: http://www.flickr.com/services/api/keys and sign up. Your should get your key right away.

3. Add the config into your web.config and add your API key.

<configuration>
  <configSections>
    <section name="flickrNet" type="FlickrNet.FlickrConfigurationManager,FlickrNet"
       allowLocation="true" />

    ...
  </configSections>

  <flickrNet apiKey="yourFlickrAPIKeyGoesHere" secret="yourSecretGoesHere"
       cacheDisabled="true" >
  </flickrNet>

...

<configuration>

This could be an external file as well.

If you want to use the FlickrNet caching, then make your config section look something like this:

  <flickrNet apiKey="yourFlickrAPIKeyGoesHere" secret="yourSecretGoesHere"
       cacheLocation="C:\\YOURWEBSITELOCATION\\App_Data" cacheSize="26240000" cacheTimeout="1:00:00" >
  </flickrNet>

4. Add the FlickrPhotoList Macro to a page or template.  It should display a list of Tree photos.

To customize the search see the documentation below.

Feel free to ask questions or comment below. The rest of the post will be the method documentation and the format that the search results are returned.

Methods

Note: all methods have nearly the same parameters so I will only list the new or different params after the first method description.

ByUser()

Summary: Use the Flickr API to search for all photos by a user.

Params:

• flickrUserId: User Id from Flickr (i.e. 12345678@N12)
• flickrSizeMSTB:
  • s = small square 75×75
  • t = thumbnail, 100 on longest side
  • m = small, 240 on longest side
  • - = medium, 500 on longest side (default)
  • b = large, 1024 on longest side (only exists for very large original images)
• flickrThumbSizeMSTB:
  • s = small square 75×75
  • t = thumbnail, 100 on longest side
• numberOfPhotos: Integer. The maximum allowed value is 500.
• flickrSortOrder: The possible values are: date-posted-asc, date-posted-desc, date-taken-asc, date-taken-desc, interestingness-desc (default), interestingness-asc, and relevance
• minTakenDate: Minimum taken date. Photos with an taken date greater than or equal to this value will be returned.
• maxTakenDate: Maximum taken date. Photos with an taken date less than or equal to this value will be returned.

Returns: XML resultset (XPathNodeIterator)

XPathNodeIterator ByUser(string flickrUserId, string flickrSizeMSTB, string flickrThumbSizeMSTB, int numberOfPhotos, string flickrSortOrder, string minTakenDate, string maxTakenDate)

ByGroup()

Summary: Use the Flickr API to search for all photos by a group id.

Params:

• flickrGroupId: Group Id from Flickr (i.e. 12345678@N12)
• NOTE: Same params as ByUser with the exception of “flickrUserId”

XPathNodeIterator ByGroup(string flickrGroupId, string flickrSizeMSTB, string flickrThumbSizeMSTB, int numberOfPhotos, string flickrSortOrder, string minTakenDate, string maxTakenDate)

ByFreeText()

Summary: Use the Flickr API to search for all photos for a full text search of title, tags, and description.

Params:

• searchText: A free text search. Photos who’s title, description or tags contain the text will be returned. You can exclude results that match a term by prepending it with a – character.
• NOTE: Same params as ByUser with the exception of “flickrUserId”

XPathNodeIterator ByFreeText(string searchText, string flickrSizeMSTB, string flickrThumbSizeMSTB, int numberOfPhotos, string flickrSortOrder, string minTakenDate, string maxTakenDate)

ByTag()

Summary: Use the Flickr API to search for all photos by one or more comma separated tags.

Params:

• tagsCommaSeparated: A comma-delimited list of tags. Photos with one or more of the tags listed will be returned. You can exclude results that match a term by prepending it with a – character.
• tagMode: Either ‘any’ for an OR combination of tags, or ‘all’ for an AND combination. Defaults to ‘any’ if not specified.
• NOTE: Same params as ByUser with the exception of “flickrUserId”

XPathNodeIterator ByTag(string tagsCommaSeparated, string tagMode, string flickrSizeMSTB, string flickrThumbSizeMSTB, int numberOfPhotos, string flickrSortOrder, string minTakenDate, string maxTakenDate)

ByUserAndTag()

Summary: Use the Flickr API to search for all photos by one or more comma separated tags for a user.

Params:

• flickrUserId: User Id from Flickr (i.e. 12345678@N12)
• tagsCommaSeparated: A comma-delimited list of tags. Photos with one or more of the tags listed will be returned. You can exclude results that match a term by prepending it with a – character.
• tagMode: Either ‘any’ for an OR combination of tags, or ‘all’ for an AND combination. Defaults to ‘any’ if not specified.
• NOTE: Same params as ByTag with the exception of “flickrUserId”

XPathNodeIterator ByUserAndTag(string flickrUserId, string tagsCommaSeparated, string tagMode, string flickrSizeMSTB, string flickrThumbSizeMSTB, int numberOfPhotos, string flickrSortOrder, string minTakenDate, string maxTakenDate)

BySet()

Summary: Use the Flickr API to search for all photos in a set.

Params:

• photoSetId: The id of the photoset to return the photos for.
• numberOfPhotosPerPage: Integer. Number of photos per page. The maximum allowed value is 500.
• page: Integer. The page of results to return.
• NOTE: The flickrSizeMSTB and flickrThumbSizeMSTB work the same as the other methods.

XPathNodeIterator BySet(string photoSetId, int numberOfPhotosPerPage, int page, string flickrSizeMSTB, string flickrThumbSizeMSTB)

Additional Methods “WithPaging”

Summary: Allows for paging on Flickrs end.  Adds a new parameter “page” and replaces “numberOfPhotos” with “photosPerPage”.

Params:

• page: Integer. The page of results to return.
• photosPerPage: Integer. Number of photos per page. The maximum allowed value is 500.
• NOTE: Same params as related method
  

Result XML

Fields:

<photolist> contains many <photo>s

<photo> object attributes:

• title: Image title as set by the image owner
• imagefile: File location URL on Flickr in the size specified by the “flickrSizeMSTB” param
• thumbnail: File location URL on Flickr in the size specified by the “flickrThumbSizeMSTB” param
• flickrpageurl: URL to the Flickr page for this photo
• ownername: Flickr user that has the photo on their account
• latitude: Latitude this photo was taken at
• longitude: Longitude this photo was taken at
• datetaken: Date photo was taken
• tags: tags assigned to this photo
• views: views on Flickr of this image

Sample:

<photolist>
<photo title="Call of the Raven (formerly Nature's Special Effects)" imagefile="http://farm1.static.flickr.com/33/63452603_b3a5b5448d.jpg" thumbnail="http://farm1.static.flickr.com/33/63452603_b3a5b5448d_t.jpg" flickrpageurl="http://www.flickr.com/photos/72164905@N00/63452603" ownername="Walkabout Wolf" latitude="47.149625" longitude="-121.566724" datetaken="2005/11/14" tags="" views="-1"></photo>
<photo title="Fascinating Nature - First Double Rainbow 2010" imagefile="http://farm3.static.flickr.com/2710/4466953793_cd0430ba59.jpg" thumbnail="http://farm3.static.flickr.com/2710/4466953793_cd0430ba59_t.jpg" flickrpageurl="http://www.flickr.com/photos/21207178@N07/4466953793" ownername="Batikart" latitude="48.798242" longitude="9.280571" datetaken="2010/03/27" tags="" views="-1"></photo>
<photo title="The Earth, The Sky And A Tree" imagefile="http://farm5.static.flickr.com/4016/4457682328_5425b08a1e.jpg" thumbnail="http://farm5.static.flickr.com/4016/4457682328_5425b08a1e_t.jpg" flickrpageurl="http://www.flickr.com/photos/8407953@N03/4457682328" ownername=".: Philipp Klinger :." latitude="50.377929" longitude="8.774814" datetaken="2010/03/22" tags="" views="-1"></photo>
<photo title="Touchdown, Part II" imagefile="http://farm5.static.flickr.com/4061/4398070785_453712aaef.jpg" thumbnail="http://farm5.static.flickr.com/4061/4398070785_453712aaef_t.jpg" flickrpageurl="http://www.flickr.com/photos/8407953@N03/4398070785" ownername=".: Philipp Klinger :." latitude="50.378586" longitude="8.767776" datetaken="2009/06/07" tags="" views="-1"></photo>
</photolist>