class Flickr

Flickr client class. Requires an API key

Constants

API_PATH
HOST_URL
VALID_SIZES: Flickr, annoyingly, uses a number of representations to specify the size of a photo, depending on the context. It gives a label such a “Small” or “Medium” to a size of photo, when returning all possible sizes. However, when generating the uri for the page that features that size of photo, or the source url for the image itself it uses a single letter. Bizarrely, these letters are different depending on whether you want the Flickr page for the photo or the source uri – e.g. a “Small” photo (240 pixels on its longest side) may be viewed at “www.flickr.com/photos/sco/2397458775/sizes/s/” but its source is at “”. The VALID_SIZES hash associates the correct letter with a label

Attributes

api_key[R]

auth_token[R]

user[RW]

Public Class Methods

new(api_key_or_params={}) click to toggle source

To use the Flickr API you need an api key (see www.flickr.com/services/api/misc.api_keys.html), and the flickr client object shuld be initialized with this. You’ll also need a shared secret code if you want to use authentication (e.g. to get a user’s private photos) There are two ways to initialize the Flickr client. The preferred way is with a hash of params, e.g. ‘api_key’ => ‘your_api_key’, ‘shared_secret’ => ‘shared_secret_code’, ‘verify_ssl’ => true, ‘ca_file’ => ‘/path/to/cert.pem’. Other way is to use in Rails an config file RAILS_ROOT/config/flickr.api.yml and there use params as key/values even specified for every environment.

# File lib/flickr.rb, line 81
def initialize(api_key_or_params={})
  @host = HOST_URL
  @api = API_PATH
  @verify_ssl = true
  api_key_or_params={} if api_key_or_params.nil? # fix for nil value as argument
  api_key_or_params = {:api_key => api_key_or_params} if api_key_or_params.is_a?(String)
  api_key_or_params = Config.get if Config.parsed? and api_key_or_params.empty?
  set_up_configuration api_key_or_params if api_key_or_params.is_a? Hash
end

Public Instance Methods

find_by_url(url) click to toggle source

Implements flickr.urls.lookupGroup and flickr.urls.lookupUser

# File lib/flickr.rb, line 113
def find_by_url(url)
  response = urls_lookupUser('url'=>url) rescue urls_lookupGroup('url'=>url) rescue nil
  (response['user']) ? User.new(response['user']['id'], nil, nil, nil, @api_key) : Group.new(response['group']['id'], @api_key) unless response.nil?
end

get_token_from(frob) click to toggle source

Gets authentication token given a Flickr frob, which is returned when user allows access to their account for the application with the api_key which made the request

# File lib/flickr.rb, line 102
def get_token_from(frob)
  auth_response = request("auth.getToken", :frob => frob)['auth']
  @auth_token = auth_response['token']
  @user = User.new( 'id' => auth_response['user']['nsid'],
                    'username' => auth_response['user']['username'],
                    'name' => auth_response['user']['fullname'],
                    'client' => self)
  @auth_token
end

groups(group_name, options={}) click to toggle source

Implements flickr.groups.search

# File lib/flickr.rb, line 146
def groups(group_name, options={})
  collection = groups_search({"text" => group_name}.merge(options))['groups']['group']
  collection = [collection] if collection.is_a? Hash

  collection.collect { |group| Group.new( "id" => group['nsid'],
                                          "name" => group['name'],
                                          "eighteenplus" => group['eighteenplus'],
                                          "client" => self) }
end

http_get(url) click to toggle source

Does an HTTP GET on a given URL and returns the response body

# File lib/flickr.rb, line 184
def http_get(url)
  url = URI.parse(url)
  http = Net::HTTP.new url.host, url.port
  http.use_ssl = true
  http.verify_mode = (@verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE)
  http.ca_file = @ca_file if @ca_file
  http.start do |res|
    res.request_get(url.request_uri).body.to_s
  end
end

licenses() click to toggle source

Implements flickr.photos.licenses.getInfo

# File lib/flickr.rb, line 166
def licenses
  photos_licenses_getInfo['licenses']['license']
end

login_url(perms) click to toggle source

Returns url for user to login in to Flickr to authenticate app for a user

# File lib/flickr.rb, line 171
def login_url(perms)
  "https://flickr.com/services/auth/?api_key=#{@api_key}&perms=#{perms}&api_sig=#{signature_from('api_key'=>@api_key, 'perms' => perms)}"
end

method_missing(method_id, params={}) click to toggle source

Implements everything else. Any method not defined explicitly will be passed on to the Flickr API, and return an XmlSimple document. For example, Flickr#test_echo is not defined, so it will pass the call to the flickr.test.echo method.

# File lib/flickr.rb, line 179
def method_missing(method_id, params={})
  request(method_id.id2name.gsub(/_/, '.'), params)
end

photos(*criteria) click to toggle source

Implements flickr.photos.getRecent and flickr.photos.search

# File lib/flickr.rb, line 119
def photos(*criteria)
  not criteria.empty? and photos_search(*criteria) or recent
end

photos_request(method, params={}, list_node="photos") click to toggle source

acts like request but returns a PhotoCollection (a list of Photo objects)

# File lib/flickr.rb, line 204
def photos_request(method, params={}, list_node="photos")
  photos = request(method, params)
  PhotoCollection.new(photos, @api_key, list_node)
end

photos_search(params={}) click to toggle source

# File lib/flickr.rb, line 129
def photos_search(params={})
  photos_request('photos.search', params)
end

Also aliased as: search

photoset(photoset_id) click to toggle source

# File lib/flickr.rb, line 156
def photoset(photoset_id)
  Photoset.new(photoset_id, @api_key)
end

recent() click to toggle source

flickr.photos.getRecent 100 newest photos from everyone

# File lib/flickr.rb, line 125
def recent
  photos_request('photos.getRecent')
end

related_tags(tag) click to toggle source

Implements flickr.tags.getRelated

# File lib/flickr.rb, line 161
def related_tags(tag)
  tags_getRelated('tag'=>tag)['tags']['tag']
end

request(method, params={}) click to toggle source

Takes a Flickr API method name and set of parameters; returns an XmlSimple object with the response

# File lib/flickr.rb, line 196
def request(method, params={})
  url = request_url(method, params)
  response = XmlSimple.xml_in(http_get(url), { 'ForceArray' => false })
  raise response['err']['msg'] if response['stat'] != 'ok'
  response
end

request_url(method, params={}) click to toggle source

Builds url for Flickr API REST request from given the flickr method name (exclusing the ‘flickr.’ that begins each method call) and params (where applicable) which should be supplied as a Hash (e.g ‘user_id’ => “foo123”)

# File lib/flickr.rb, line 212
def request_url(method, params={})
  method = 'flickr.' + method
  url = "#{@host}#{@api}/?api_key=#{@api_key}&method=#{method}"
  params.merge!('api_key' => @api_key, 'method' => method, 'auth_token' => @auth_token)
  signature = signature_from(params)

  url = "#{@host}#{@api}/?" + params.merge('api_sig' => signature).collect { |k,v| "#{k}=" + CGI::escape(v.to_s) unless v.nil? }.compact.join("&")
end

search(params={})

Alias for: photos_search

set_up_configuration(api_key_or_params = {}) click to toggle source

# File lib/flickr.rb, line 91
def set_up_configuration api_key_or_params = {}
  @api_key = api_key_or_params[:api_key]
  @shared_secret = api_key_or_params[:shared_secret]
  @auth_token = api_key_or_params[:auth_token]
  @ca_file = api_key_or_params[:ca_file]
  @verify_ssl = !(api_key_or_params[:verify_ssl].to_s === 'false')
end

signature_from(params={}) click to toggle source

# File lib/flickr.rb, line 221
def signature_from(params={})
  return unless @shared_secret # don't both getting signature if no shared_secret
  request_str = params.reject {|k,v| v.nil?}.collect {|p| "#{p[0].to_s}#{p[1]}"}.sort.join # build key value pairs, sort in alpha order then join them, ignoring those with nil value
  return Digest::MD5.hexdigest("#{@shared_secret}#{request_str}")
end

tag(tag) click to toggle source

Gets public photos with a given tag

# File lib/flickr.rb, line 135
def tag(tag)
  photos('tags'=>tag)
end

users(lookup=nil) click to toggle source

Implements flickr.people.findByEmail and flickr.people.findByUsername.

# File lib/flickr.rb, line 140
def users(lookup=nil)
  user = people_findByEmail('find_email'=>lookup)['user'] rescue people_findByUsername('username'=>lookup)['user']
  return User.new("id" => user["nsid"], "username" => user["username"], "client" => self)
end