An object-oriented wrapper for the Flickr API.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
spec
.gitignore
.yardopts
CHANGELOG.md
CONTRIBUTING.md
Gemfile
LICENSE
README.md
Rakefile
flickr-objects.gemspec

README.md

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"
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: "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.

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.