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.searchis a class API method. AndFlickr.people.get_setsis by its nature an instance API method, because we're finding sets from a person; in that case it's nicer to call#get_setson an instance of person. - Flickr objects can always be instantiated with
Flickr.<objects>.find(id)(in the above example we didFlickr.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: "[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("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.