Module: Fleakr

Defined in:
lib/fleakr.rb,
lib/fleakr/version.rb,
lib/fleakr/api/option.rb,
lib/fleakr/objects/tag.rb,
lib/fleakr/objects/set.rb,
lib/fleakr/objects/url.rb,
lib/fleakr/objects/user.rb,
lib/fleakr/api/response.rb,
lib/fleakr/objects/error.rb,
lib/fleakr/objects/photo.rb,
lib/fleakr/support/cache.rb,
lib/fleakr/objects/group.rb,
lib/fleakr/objects/image.rb,
lib/fleakr/objects/search.rb,
lib/fleakr/support/object.rb,
lib/fleakr/support/utility.rb,
lib/fleakr/objects/contact.rb,
lib/fleakr/objects/comment.rb,
lib/fleakr/support/request.rb,
lib/fleakr/objects/metadata.rb,
lib/fleakr/support/attribute.rb,
lib/fleakr/objects/collection.rb,
lib/fleakr/api/parameter_list.rb,
lib/fleakr/api/method_request.rb,
lib/fleakr/api/upload_request.rb,
lib/fleakr/api/file_parameter.rb,
lib/fleakr/api/value_parameter.rb,
lib/fleakr/support/association.rb,
lib/fleakr/support/url_expander.rb,
lib/fleakr/objects/photo_context.rb,
lib/fleakr/api/authentication_request.rb,
lib/fleakr/objects/metadata_collection.rb,
lib/fleakr/objects/authentication_token.rb

Overview

Fleakr: A small, yet powerful, gem to interface with Flickr photostreams

Quick Start

Getting started is easy, just make sure you have a valid API key from Flickr and you can then start making any non-authenticated request to pull back data for yours and others' photostreams, sets, contacts, groups, etc...

For now, all activity originates from a single user which you can find by username or email address.

Example:

require 'rubygems'
require 'fleakr'

# Our API key is ABC123 (http://www.flickr.com/services/api/keys/apply/)
Fleakr.api_key = 'ABC123'
user = Fleakr.user('bees')
user = Fleakr.user('user@host.com')
# Grab a list of sets
user.sets
# Grab a list of the user's public groups
user.groups

To see what other associations and attributes are available, see the Fleakr::Objects::User class

Authentication

If you want to do something more than just retrieve public photos (like upload your own), you'll need to generate an authentication token to use across requests and sessions.

Assuming you've already applied for a key, go back and make sure you have the right settings to get your auth token. Click on the 'Edit key details' link and ensure that:

  1. Your application description and notes are up-to-date

  2. The value for 'Authentication Type' is set to 'Mobile Application'

  3. The value for 'Mobile Permissions' is set to either 'write' or 'delete'

Once this is set, you'll see your Authentication URL on the key details page (it will look something like www.flickr.com/auth-534525246245). Paste this URL into your browser and confirm access to get your mini-token. Now you're ready to make authenticated requests:

require 'rubygems'
require 'fleakr'

Fleakr.api_key       = 'ABC123'
Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
Fleakr.mini_token    = '362-133-214'

Fleakr.upload('/path/to/my/photo.jpg')
Fleakr.token.value # => "34132412341235-12341234ef34"

Once you use the mini-token once, it is no longer available. To use the generated auth_token for future requests, just set Fleakr.auth_token to the generated value.

Defined Under Namespace

Modules: Api, Objects, Support, Version Classes: ApiError

Class Attribute Summary (collapse)

Class Method Summary (collapse)

Class Attribute Details

+ (Object) api_key

Returns the value of attribute api_key



80
81
82
 
# File 'lib/fleakr.rb', line 80

def api_key
  @api_key
end

+ (Object) auth_token

Returns the value of attribute auth_token



80
81
82
 
# File 'lib/fleakr.rb', line 80

def auth_token
  @auth_token
end

+ (Object) shared_secret

Returns the value of attribute shared_secret



80
81
82
 
# File 'lib/fleakr.rb', line 80

def shared_secret
  @shared_secret
end

Class Method Details

+ (Object) authorization_url(permissions = :read)

Generate an authorization URL to redirect users to. This defaults to 'read' permission, but others are available when passed to this method:

* :read - permission to read private information (default)
* :write - permission to add, edit and delete photo metadata (includes 'read')
* :delete - permission to delete photos (includes 'write' and 'read')


161
162
163
164
 
# File 'lib/fleakr.rb', line 161

def self.authorization_url(permissions = :read)
  request = Fleakr::Api::AuthenticationRequest.new(:perms => permissions)
  request.authorization_url
end

+ (Object) contacts(contact_type = nil, additional_options = {})

Get all contacts for the currently authenticated user. The provided contact type can be one of the following:

:friends

Only contacts who are friends (and not family)

:family

Only contacts who are family (and not friends)

:both

Only contacts who are both friends and family

:neither

Only contacts who are neither friends nor family

Additional parameters supported are:

:page

The page of results to return

:per_page

The number of contacts to retrieve per page



146
147
148
149
150
151
152
 
# File 'lib/fleakr.rb', line 146

def self.contacts(contact_type = nil, additional_options = {})
  options = {}
  options.merge!(:filter => contact_type) unless contact_type.nil?
  options.merge!(additional_options)

  Fleakr::Objects::Contact.find_all(options)
end

+ (Object) resource_from_url(url)

Retrieve a photo, person, or set from a flickr.com URL:



189
190
191
 
# File 'lib/fleakr.rb', line 189

def self.resource_from_url(url)
  Fleakr::Objects::Url.new(url).resource
end

+ (Object) search(params)

Search all photos on the Flickr site. By default, this searches based on text, but you can pass different search parameters (passed as hash keys):

tags

The list of tags to search on (either as an array or comma-separated)

user_id

Scope the search to this user

group_id

Scope the search to this group

If you're interested in User- and Group-scoped searches, you may want to use User#search and Group#search instead.



114
115
116
117
 
# File 'lib/fleakr.rb', line 114

def self.search(params)
  params = {:text => params} unless params.is_a?(Hash)
  Objects::Search.new(params).results
end

+ (Object) token_from_frob(frob)

Exchange a frob for an authentication token. See Fleakr.authorization_url for more information.



169
170
171
 
# File 'lib/fleakr.rb', line 169

def self.token_from_frob(frob)
  Fleakr::Objects::AuthenticationToken.from_frob(frob)
end

+ (Object) token_from_mini_token(mini_token)

Exchange a mini token for an authentication token.



175
176
177
 
# File 'lib/fleakr.rb', line 175

def self.token_from_mini_token(mini_token)
  Fleakr::Objects::AuthenticationToken.from_mini_token(mini_token)
end

+ (Object) upload(glob, options = {})

Upload one or more files to your Flickr account (requires authentication). Simply provide a filename or a pattern to upload one or more files:

Fleakr.upload('/path/to/my/mug.jpg')
Fleakr.upload('/User/Pictures/Party/*.jpg')

Additionally, options can be supplied as part of the upload that will apply to all files that are matched by the pattern passed to glob. For a full list, see Fleakr::Objects::Photo.



129
130
131
 
# File 'lib/fleakr.rb', line 129

def self.upload(glob, options = {})
  Dir[glob].map {|file| Fleakr::Objects::Photo.upload(file, options) }
end

+ (Object) user(user_data, options = {})

TODO: Use User.find_by_identifier for some of this



94
95
96
97
98
99
100
101
102
 
# File 'lib/fleakr.rb', line 94

def self.user(user_data, options = {})
  user = nil
  [:username, :email, :url].each do |attribute|
    if user.nil?
      user = Objects::User.send("find_by_#{attribute}", user_data, options) rescue nil
    end
  end
  user
end

+ (Object) user_for_token(auth_token)

Get the user that this authentication token belongs to. Useful for pulling relationships scoped to this user.



182
183
184
185
 
# File 'lib/fleakr.rb', line 182

def self.user_for_token(auth_token)
  token = Fleakr::Objects::AuthenticationToken.from_auth_token(auth_token)
  token.user
end