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

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.

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)).

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: "janko.marohnic@gmail.com")

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

Flickr.people.find_by_email("janko.marohnic@gmail.com")

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

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.

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.

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

See Flickr.upload.

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).

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

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.