Flickr Objects

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

• Web page: http://janko.github.com/flickr-objects
• Source code: https://github.com/janko/flickr-objects
• API Documentation: http://rubydoc.info/github/janko/flickr-objects/master/frames

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"
end

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

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

Usage

This gem maps Flickr's API methods to Ruby methods.

Flickr.photos.search(...)   # flickr.photos.search
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.

Example:

photos = Flickr.photos.search(user_id: "78733179@N04") #=> [#<Flickr::Object::Photo: ...>, #<Flickr::Object::Photo: ...>, ...]

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

person = Flickr.people.find("78733179@N04")
set = person.sets.first
set.id           #=> "11243423"
set.photos_count #=> 40

Few notes here:

• flickr-objects distinguishes instance from class API methods. So, Flickr.photos.search 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.

Sizes

person = Flickr.person.find("78733179@N04")
photo = person.public_photos(sizes: true).first

photo.small!(320)
photo.source_url #=> "http://farm9.staticflickr.com/8191/8130464513_780e01decd_n.jpg"
photo.width      #=> 320
photo.height     #=> 280

photo.medium!(500)
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("78733179@N04")
    @photos = person.public_photos(sizes: true).map(&:medium500!)
  end
end

<% @photos.each do |photo| %>
  <%= image_tag photo.source_url, size: "#{photo.width}x#{photo.height}" %>
<% end %>

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

Authentication

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

flickr = Flickr.new("ACCESS_TOKEN_KEY", "ACCESS_TOKEN_SECRET")

# It has the same interface as `Flickr`
flickr.test_login #=> {"id" => "78733179@N04", "username" => ...}
flickr.people.find("78733179@N04").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"
end

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

Upload

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

See Flickr.upload.

Pagination

Flickr.configure do |config|
  config.pagination = :will_paginate
end

@photos = Flickr.photos.search(user_id: "78733179@N04", 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).

Caching

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

Flickr.photos.recent # Makes an API call
Flickr.photos.recent # 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 ;)

Social

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

License

This project is released under the MIT license.