Module: Fleakr

Defined in:
lib/fleakr.rb,
lib/fleakr/version.rb,
lib/fleakr/api/option.rb,
lib/fleakr/objects/set.rb,
lib/fleakr/objects/tag.rb,
lib/fleakr/objects/url.rb,
lib/fleakr/api/response.rb,
lib/fleakr/objects/user.rb,
lib/fleakr/objects/error.rb,
lib/fleakr/objects/group.rb,
lib/fleakr/objects/image.rb,
lib/fleakr/objects/photo.rb,
lib/fleakr/objects/search.rb,
lib/fleakr/support/object.rb,
lib/fleakr/objects/comment.rb,
lib/fleakr/objects/contact.rb,
lib/fleakr/support/request.rb,
lib/fleakr/support/utility.rb,
lib/fleakr/objects/metadata.rb,
lib/fleakr/support/attribute.rb,
lib/fleakr/api/file_parameter.rb,
lib/fleakr/api/method_request.rb,
lib/fleakr/api/parameter_list.rb,
lib/fleakr/api/upload_request.rb,
lib/fleakr/objects/collection.rb,
lib/fleakr/api/value_parameter.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('[email protected]')
# 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

.api_key ⇒ Object

Returns the value of attribute api_key.



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

def api_key
  @api_key
end

.auth_token ⇒ Object

Returns the value of attribute auth_token.



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

def auth_token
  @auth_token
end

.shared_secret ⇒ Object

Returns the value of attribute shared_secret.



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

def shared_secret
  @shared_secret
end

Class Method Details

.authorization_url(permissions = :read) ⇒ Object

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



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

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

.contacts(contact_type = nil, additional_options = {}) ⇒ Object

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



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

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

.resource_from_url(url) ⇒ Object

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



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

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

.search(params) ⇒ Object

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.



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

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

.token_from_frob(frob) ⇒ Object

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



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

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

.token_from_mini_token(mini_token) ⇒ Object

Exchange a mini token for an authentication token.



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

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

.upload(glob, options = {}) ⇒ Object

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.



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

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

.user(user_data, options = {}) ⇒ Object

TODO: Use User.find_by_identifier for some of this



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

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

.user_for_token(auth_token) ⇒ Object

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



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

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