Flickr Objects

This gem is an object-oriented wrapper for the Flickr API.

The gem has been tested on the following Ruby versions:

  • MRI 1.9.3
  • MRI 2.0
  • MRI 2.1

Installation and setup

Add it to your Gemfile, and run bundle install.

gem "flickr-objects"

Now create an initializer where you set your Flickr credentials.

Flickr.configure do |config|
  config.api_key       = "API_KEY"
  config.shared_secret = "SHARED_SECRET"

If you don't have them yet, you can apply for them here.

For list of possible configuration options, see Flickr::Configuration.


This gem maps Flickr's API methods to Ruby methods.   #
Flickr.person.get_sets(...) # flickr.photosets.getList

For the list of all API methods (and their related Flickr's methods), see Flickr::Api. These methods are included to the Flickr module.


photos = "[email protected]") #=> [#<Flickr::Object::Photo: ...>, #<Flickr::Object::Photo: ...>, ...]

photo = photos.first                 #=> "231233252"
photo.title              #=> "My cat"
photo.visibility.public? #=> true

person = Flickr.people.find("[email protected]")
set = person.sets.first           #=> "11243423"
set.photos_count #=> 40

Few notes here:

  • flickr-objects distinguishes instance from class API methods. So, is a class API method. And Flickr.people.get_sets is by its nature an instance API method, because we're finding sets from a person; in that case it's nicer to call #get_sets on an instance of person.
  • Flickr objects can always be instantiated with Flickr.<objects>.find(id) (in the above example we did Flickr.people.find(id)).

Arguments to API methods

By its nature, API methods always accept a hash of parameters. Using that approach, this would be the call for "flickr.people.findByEmail":

Flickr.people.find_by_email(find_email: "[email protected]")

But that looks lame. Luckily, in these kind of methods flickr-objects improves the argument list:

Flickr.people.find_by_email("[email protected]")

These arguments are documented: Flickr::Api::Person#find_by_email.


person = Flickr.person.find("[email protected]")
photo = person.public_photos(sizes: true).first

photo.source_url #=> ""
photo.width      #=> 320
photo.height     #=> 280

photo.width      #=> 500

It is important here that you pass sizes: true to Flickr::Person#public_photos. So, in your (Rails) application, you could use it like this:

class PhotosController < ApplicationController
  def index
    person = Flickr.people.find("[email protected]")
    @photos = person.public_photos(sizes: true).map(&:medium500!)
<% @photos.each do |photo| %>
  <%= image_tag photo.source_url, size: "#{photo.width}x#{photo.height}" %>
<% end %>

To find out more, see Flickr::Object::Photo.


You may need to make authenticated API requests, using an access token.


# It has the same interface as `Flickr`
flickr. #=> {"id" => "[email protected]", "username" => ...}
flickr.people.find("[email protected]").get_photos #=> [#<Flickr::Photo ...>, #<Flickr::Photo, ...>, ...]

For details on how to authenticate the user, that is, obtain his access token, see Flickr::OAuth.

If you want, you can also assign the access token globally in your configuration.

Flickr.configure do |config|
  config.access_token_key = "ACCESS_TOKEN_KEY"
  config.access_token_secret = "ACCESS_TOKEN_SECRET"

Naturally, this way you don't need to create an instance like above.


photo_id = Flickr.upload("/path/to/photo.jpg", title: "Dandelions")
photo =!
photo.title #=> "Dandelions"

See Flickr.upload.


Flickr.configure do |config|
  config.pagination = :will_paginate
@photos = "[email protected]", page: params[:page], per_page: 10)
<%= will_paginate @photos %>

Flickr gives you pagination on almost every request that returns a collection of objects. This gem supports both WillPaginate (:will_paginate) and Kaminari (:kaminari).


To enable caching responses, just pass in a cache object (an object that responds to #read, #write and #fetch) in the configuration.

require "active_support/cache"
require "active_support/core_ext/numeric/time"

Flickr.configure do |config|
  config.cache = ActiveSupport::Cache::MemoryStore(expires_in: 1.week)
end # Makes an API call # Uses the cache

Few words

Many of the API methods are not covered yet (because they are so many). I believe I covered all the important ones, but if you wish for me to cover certain new ones, feel free to contact me via Twitter. I also wouldn't mind getting a pull request ;)


You can follow me on Twitter, I'm @jankomarohnic.


This project is released under the MIT license.