Fleakr¶ ↑

A small, yet powerful, gem to interface with Flickr photostreams

sudo gem install fleakr

$ git clone git://github.com/reagent/fleakr.git
$ cd fleakr
$ rake gem && sudo gem install pkg/fleakr-<version>.gem

To get started, you’ll need to grab an API key from Flickr to at least perform any of the non-authenticated, read-only calls. Head on over to the Flickr site to grab one, I’ll be here when you get back: www.flickr.com/services/api/misc.api_keys.html

Now that you have your key, you can get things rolling with irb and the fleakr gem:

$ irb -r rubygems
>> require 'fleakr'

Then, set your API key (only need to do this once per session):

>> Fleakr.api_key = '<your api key here>'

With just an API key, you have the ability to retrieve a substantial amount of data about users, their photosets, photos, contacts, and groups. Let’s start by finding a user by his username:

>> user = Fleakr.user('the decapitator')
=> #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06">

By email:

>> user = Fleakr.user('user@host.com')
=> #<Fleakr::Objects::User:0x11f484c @username="bckspcr", @id="84481630@N00">

Or even by URL:

>> user = Fleakr.user('http://www.flickr.com/photos/the_decapitator/')
=> #<Fleakr::Objects::User:0x113440c @username="the decapitator", @id="21775151@N06">

Once you have a user, you can find his associated sets:

>> user.sets
=> [#<Fleakr::Objects::Set:0x671358 @title="The Decapitator", @description="">,
    #<Fleakr::Objects::Set:0x66d898 @title="londonpaper hijack", ...

His individual photos:

>> user.photos.first
=> #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >

Or contacts:

>> user.contacts.first
=> #<Fleakr::Objects::User:0x19039bc @username=".schill",
    @id="12289718@N00", @icon_farm="1", @icon_server="4">

Or his groups if you would like:

>> user.groups
=> [#<Fleakr::Objects::Group:0x11f2330 ...,
    #<Fleakr::Objects::Group:0x11f2308 ...
>> user.groups.first.name
=> "Rural Decay"
>> user.groups.first.id
=> "14581414@N00"

Groups also contain photos:

>> user.groups.last.photos.first.title
=> "Welcome To The Machine"

When accessing a set, you can also grab all the photos that are in that set:

>> user.sets.first
=> #<Fleakr::Objects::Set:0x1195bbc @title="The Decapitator", @id="72157603480986566", @description="">
>> user.sets.first.photos.first
=> #<Fleakr::Objects::Photo:0x1140108 ... >
>> user.sets.first.photos.first.title
=> "Untitled1"

Besides pulling back a given user’s public contacts list, you can also retrieve the list of contacts for the currently authenticated user (see below about authentication). For example, you can retrieve all contacts:

>> Fleakr.contacts
=> [#<Fleakr::Objects::Contact:0x111ff84 @username="bryan.ray" ...>]

Or just the contacts marked as ‘family’:

>> Fleakr.contacts(:family)
=> [#<Fleakr::Objects::Contact:0x12db42c @username="Grandbob" ...>]

Or a specific page of contacts marked as ‘friends’:

>> Fleakr.contacts(:friends, :page => 3, :per_page => 5)
=> [#<Fleakr::Objects::Contact:0x12a6c54 @username="Louise and BCG" ...>]

See the documentation for Fleakr.contacts for what options are available.

Each photo object contains metadata about a collection of images, each representing different sizes. Once we have a single photo:

>> photo = user.photos.first
=> #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >

We can get information about one of the sizes:

>> photo.small
=> #<Fleakr::Objects::Image:0x1768f1c @height="172", @size="Small", @width="240",
    @url="http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg",
    @page="http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/">

Grab the URL for the image itself:

>> photo.small.url
=> "http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg"

Or grab the URL for its page on the Flickr site:

>> photo.small.page
=> "http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/"

Other sizes are available (:square, :thumbnail, :small, :medium, :large, :original) and are accessed in the same way:

>> photo.original.url
=> "http://farm4.static.flickr.com/3250/2924549350_1cf67c2d47_o.jpg"

Tags are available for users and photos. Retrieving them is easy:

>> user = Fleakr.user('the decapitator')
>> user.tags
=> [#<Fleakr::Objects::Tag:0x190d5fc @value="ad">,
    #<Fleakr::Objects::Tag:0x1908a20 @value="ads">, ...
>> user.photos.first.tags
=> [#<Fleakr::Objects::Tag:0x17b1b18 @machine_flag="0", @author_id="21775151@N06", ...

All tags have values, but for tags associated with photos there is some additional information:

>> tag = user.photos.first.tags.first
>> tag.id
=> "21729829-3263659141-427098"
>> tag.raw
=> "decapitator"
>> tag.value
=> "decapitator"
>> tag.to_s
=> "decapitator"
>> tag.machine?
=> false
>> tag.author
=> #<Fleakr::Objects::User:0x1a149f0 @username="the decapitator", ... >

Each tag can also have related tags:

>> user.photos.first.tags[1].related.first.related.first.to_s
=> "face"

You get the idea - see Fleakr::Objects::Tag for more information.

Similar to tags, photosets and photos can each have comments:

>> user.sets.first.comments
=> [#<Fleakr::Objects::Comment:0x19795cc ...
>> user.photos.first.comments
=> [#<Fleakr::Objects::Comment:0x17bf0b0 @body="Dayum, that's some wishful thinking!" ...

All comments have additional information:

>> comment = user.photos.first.comments.first
>> comment.id
=> "21729829-3263659141-72157613553885978"
>> comment.body
=> "Dayum, that's some wishful thinking!"
>> comment.to_s
=> "Dayum, that's some wishful thinking!"
>> comment.url
=> "http://www.flickr.com/photos/the_decapitator/3263659141/#comment72157613553885978"
>> comment.author
=> #<Fleakr::Objects::User:0x178e3d4 @username="jaspertandy", ... >

See Fleakr::Objects::Comment for more information.

An individual can have zero or more collections associated with his account. These collections, in turn, can have either collections or sets associated with them. For example:

>> user = Fleakr.user('username')
>> user.collections.length
=> 1
>> user.collections.first.title
=> "The Year in Pictures"
>> user.collections.first.collections.length
=> 2
>> user.collections.first.collections.first.sets.length
=> 3
>> user.collections.first.collections.first.sets.first.title
=> "A Trip to Yosemite"

Note that collections are limited to Flickr pro members. See Fleakr::Objects::Collection for more information.

Sometimes you want to retrieve a person, set, or photo but you only have the public Flickr URL for that entity. Retrieval is easy:

>> Fleakr.resource_from_url('http://www.flickr.com/people/reagent/')
=> #<Fleakr::Objects::User @id="25073988@N05", @username="reagent", @authentication_options={}>

This method also supports the retrieval of photos from a shortened Flickr URL:

>> Fleakr.resource_from_url('http://flic.kr/p/95Nr83')
=> #<Fleakr::Objects::Photo @id="5305179788", @title="Comic Sans Sign", ... >

If a photo interests you, save it down to a directory of your choosing:

>> photo.original.save_to('/tmp')
=> #<File:/tmp/2924549350_1cf67c2d47_o.jpg (closed)>

Similarly, you can save down entire sets. Just specify the target directory and the size of the images you’re interested in:

>> user.sets.first.save_to('/tmp', :square)
=> [#<Fleakr::Objects::Photo:0x1187a1c @secret="715587b2cb" ...

This creates a subdirectory within the target directory based on the set’s name and preserves the original order of the photos:

>> Dir["/tmp/#{user.sets.first.title}/*.jpg"].map
=> ["/tmp/The Decapitator/01_2117922283_715587b2cb_s.jpg",
    "/tmp/The Decapitator/02_2125604584_9c09348fd6_s.jpg",
    "/tmp/The Decapitator/03_2118696542_8af5763bde_s.jpg", ... ]

If you would prefer to just search photos, you can do that with search text:

>> photos = Fleakr.search('ponies!!')
=> [#<Fleakr::Objects::Photo:0x11f4e64 @title="hiroshima atomic garden", @id="3078234390">,
    #<Fleakr::Objects::Photo:0x11f4928 @title="PONYLOV", @id="3077360853">, ...
>> photos.first.title
=> "hiroshima atomic garden"

You can also search based on tags:

>> photos = Fleakr.search(:tags => 'macro')
>> photos.first.title
=> "Demure"
>> photos.first.id
=> "3076049945"

Searches can also be scoped to other entities in the system (namely Users and Groups):

>> user.groups.first.search('awesome')
=> [#<Fleakr::Objects::Photo:0x18cb4cc @server_id="2012", @id="2181921273",
     @farm_id="3", @title="", @secret="634eda7521">, ...
>> user.search('serpent')
=> [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156",
    @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">]

Exif metadata can be retrieved for a photo:

>> photo = Fleakr::Objects::Photo.find_by_id('4507120023')
>> photo.metadata.keys
=> ["ImageSize", "Optical Zoom Mode", "RedBalance", "Y-Resolution", ... ]
>> photo.metadata['ImageSize']
=> "3264x2448"

You can iterate over the available elements and grab additional information:

>> photo.metadata.map {|k, e| "#{k} => '#{e.clean}'" }
=> ["Exposure => '0.003 sec (1/400)'", "Y-Resolution => '180 dpi'", ... ]

See the documentation for Fleakr::Objects::Metadata for information on what’s available.

Before you can upload files, you need to be able to make authenticated calls to the Flickr API. Skip to the next section (Authenticated Calls) for details on how to make this work.

Uploading single files is simple:

>> Fleakr.upload('/path/to/image.jpg')
=> [#<Fleakr::Objects::Photo:0x217fb54 @updated="1236133594", @server_id="3266", ...>]

Notice that the newly-uploaded image is returned. You can further inspect / modify this as necessary. The real magic is in uploading multiple files - the upload method takes a file glob:

>> Fleakr.upload('/path/to/images/*.jpg')
=> [#<Fleakr::Objects::Photo:0x217faa0 ...>,
    #<Fleakr::Objects::Photo:0x212fb18 ...>,
    #<Fleakr::Objects::Photo:0x20e09c8 ...>]

You can also set options on the file(s) that you’re uploading:

>> Fleakr.upload('/path/to/party/images/*.jpg', :viewable_by => :everyone,
                                                :title => 'Party Pics')

The full list of options can be found in the Fleakr::Objects::Photo documentation.

While read-only access to the API gets you quite a bit of data, you’ll need to generate an authentication token if you want access to the more powerful features (like uploading your own photos).

Depending on how you intend to use the Flickr API, there are 2 methods for performing authenticated calls.

You’ll need to configure your API key to to use Mobile authentication. If you’re viewing your list of keys on the Flickr site, click on the ‘Edit key details’ link and ensure that:

1. Your application description and notes are up-to-date

2. The value for ‘Authentication Type’ is set to ‘Mobile Application’

3. The value for ‘Mobile Permissions’ is set to either ‘write’ or ‘delete’

Once this is set, you’ll see your Authentication URL on the key details page (it will look something like www.flickr.com/auth-534525246245). Paste this URL into your browser and confirm access to get your mini-token. Now you’re ready to configure your authentication token:

Fleakr.api_key       = 'ABC123'
Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site

token = Fleakr.token_from_mini_token('294-585-410')
Fleakr.auth_token = token.value

Fleakr.upload('/path/to/my/photo.jpg')

Once you use the mini-token once it is no longer available. To use the generated auth_token for future requests, you’ll need to make sure that you set the value permanently:

Fleakr.auth_token = '72157622657341094-41241e527f325abb'

If you need to have your application access other users photos on their behalf, you’ll want to use the Web authentication method. Edit your key details and make sure that:

1. Your application description and notes are up-to-date

2. The value for ‘Authentication Type’ is set to ‘Web Application’

3. You configure your callback URL to point to something valid and accessible

Make sure that your key and secret are set as above. You can then begin the process by requesting that the user authorize access to his Flickr account by redirecting to an authorization URL. I’m assuming Rails conventions here, but this should work with any Ruby web framework:

redirect_to Fleakr.authorization_url

By default, we request read permission for access. This doesn’t really do much more than what the public API allows, so you can request different permissions when asking for authorization:

# The values :read, :write, and :delete are supported
redirect_to Fleakr.authorization_url(:delete)

One the user authorizes your application, he will be redirected back to your callback URL with a frob parameter as part of the query string. You’ll need to exchange this for a token:

token = Fleakr.token_from_frob(params[:frob])

The actual authentication token is available by calling token.value in the above example. You’ll want to store this value somewhere to make future API calls on behalf of this user. To make that process easier, there is a method that you can use that will allow you to automatically scope your requests to the authenticated user:

user = Fleakr.user_for_token('72157622657341094-41241e527f325abb')

From there, you can make any of the usual calls available with the API. See Fleakr::Objects::User for more information.

Because so much of the underlying API is hidden under the covers, it’s often tough to know what’s really going on when you run into unexpected behavior. To make things easier, you can have Fleakr log all of the API traffic. Here’s how:

Fleakr.logger = Logger.new('/tmp/fleakr.log')

Now any calls to the API will log both their request and response data to that file. But be warned, this can be pretty verbose by default (especially if you’re doing file uploads). To see just the requests you need to tune the log level:

logger = Logger.new('/tmp/fleakr.log')
logger.level = Logger::INFO

Fleakr.logger = logger

Even if something doesn’t go wrong, this is a good way to get a sense for when you’re making API requests.

If there is a feature that you would like to contribute, I gladly accept pull requests. There are a few things that make my life easier when integrating your changes:

• Verify that all tests are passing (run ‘rake` from the project root)

• Keep your commits small, focused, and tested - this allows me to apply changes cleanly

• Leave the Rakefile and version information intact - if you really want to make changes, please do so in a separate commit.

Once your changes are applied, I will add you to the list of contributors.

While Fleakr started as a labor of love for me, I’m glad that others have been interested in this project enough to contribute their ideas and code:

• Gordon Anderson

• Mark Dickson

• John Guenin

• Thomas Olausson

• Robert Sköld

• Nathan Walls

• Björn Wolf

Thanks!

• Implement remaining bits of person and photo-related API calls (read-only)

• Provide a better searching interface with ruby-like option syntax

• Implement asynchronous file upload / replacement w/ ticket checking

• Implement save-able search results (e.g. Fleakr.search(‘ponies’).save_to(‘/path’, :medium))

• Implement deeper associations for core elements (e.g. tags / etc..)

• Implement write methods for photos & photosets

• Implement flickr.places.* portion of API

Copyright © 2008 Patrick Reagan (reaganpr@gmail.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.