Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hanklords/flickraw

Ruby library to access flickr api.
https://github.com/hanklords/flickraw

Last synced: about 2 months ago
JSON representation

Ruby library to access flickr api.

Awesome Lists containing this project

README 

        
= Flickraw



Flickraw is a library to access flickr[http://flickr.com] api in a simple way.

It maps exactly the methods described in {the official api documentation}[http://www.flickr.com/services/api].

It also tries to present the data returned in a simple and intuitive way.

The methods are fetched from flickr when loading the library by using introspection capabilities. So it is always up-to-date with regards to new methods added by flickr.



The github repository: http://github.com/hanklords/flickraw



= Installation

Type this in a console (you might need to be superuser)



 gem install json (This is only necessary on ruby 1.8)

 gem install flickraw



This will recreate the documentation by fetching the methods descriptions from flickr and then virtually plugging them in standard rdoc documentation.

 $ cd flickraw

 $ rake rdoc



= Features



* Minimal dependencies

* Complete support of flickr API. This doesn't require an update of the library

* Ruby syntax similar to the flickr api

* Flickr authentication

* HTTPS Support

* Photo upload

* Proxy support

* Flickr URLs helpers



= Usage



== Getting started



To use FlickRaw, you must first obtain an API key and shared secret from Flickr. You can do this by logging in to Flickr and creating an application here[https://www.flickr.com/services/apps/create/apply]. API keys are usually granted automatically and instantly.



  require 'flickraw'



  # The credentials can be provided as parameters:



  flickr = FlickRaw::Flickr.new "YOUR API KEY", "YOUR SHARED SECRET"



  # Alternatively, if the API key and Shared Secret are not provided, FlickRaw will attempt to read them

  # from environment variables:

  # ENV['FLICKRAW_API_KEY']

  # ENV['FLICKRAW_SHARED_SECRET']



  flickr = FlickRaw::Flickr.new



  # FlickRaw will raise an error if either parameter is not explicitly provided, or avilable via environment variables.



== Simple



  list   = flickr.photos.getRecent



  id     = list[0].id

  secret = list[0].secret

  info = flickr.photos.getInfo :photo_id => id, :secret => secret



  puts info.title           # => "PICT986"

  puts info.dates.taken     # => "2006-07-06 15:16:18"



  sizes = flickr.photos.getSizes :photo_id => id



  original = sizes.find { |s| s.label == 'Original' }

  puts original.width       # => "800" -- may fail if they have no original marked image



== Authentication



  token = flickr.get_request_token

  auth_url = flickr.get_authorize_url(token['oauth_token'], :perms => 'delete')



  puts "Open this url in your browser to complete the authentication process : #{auth_url}"

  puts "Copy here the number given when you complete the process."

  verify = gets.strip



  begin

    flickr.get_access_token(token['oauth_token'], token['oauth_token_secret'], verify)

    login = flickr.test.login

    puts "You are now authenticated as #{login.username} with token #{flickr.access_token} and secret #{flickr.access_secret}"

  rescue FlickRaw::FailedResponse => e

    puts "Authentication failed : #{e.msg}"

  end



If the user has already been authenticated, you can reuse the access token and access secret:



  flickr.access_token = "... Your access token ..."

  flickr.access_secret = "... Your access secret ..."



  # From here you are logged:

  login = flickr.test.login

  puts "You are now authenticated as #{login.username}"



If you need to have several users authenticated at the same time in your application (ex: a public web application) you need to create separate FlickRaw objects since it keeps the authentication data internally.



  flickr = FlickRaw::Flickr.new



== Upload



  PHOTO_PATH='photo.jpg'



  # You need to be authenticated to do that, see the previous examples.

  flickr.upload_photo PHOTO_PATH, :title => "Title", :description => "This is the description"



== Proxy



  require 'flickraw'

  FlickRaw.proxy = "http://user:[email protected]:3129/"



=== Server Certificate Verification



Server certificate verification is enabled by default. If you don't want to check the server certificate :



  require 'flickraw'

  FlickRaw.check_certificate = false



=== CA Certificate File Path



OpenSSL::X509::DEFAULT_CERT_FILE is used as a CA certificate file. If you want to change the path :



  require 'flickraw'

  FlickRaw.ca_file = '/path/to/cacert.pem'



You can also specify a path to a directory with a number of certifications:



  FlickRaw.ca_path = '/path/to/certificates'



== Flickr URL Helpers



There are some helpers to build flickr urls :



=== url, url_m, url_s, url_t, url_b, url_z, url_q, url_n, url_c, url_o



  # url_s : Square

  # url_q : Large Square

  # url_t : Thumbnail

  # url_m : Small

  # url_n : Small 320

  # url   : Medium

  # url_z : Medium 640

  # url_c : Medium 800

  # url_b : Large

  # url_o : Original



  info = flickr.photos.getInfo(:photo_id => "3839885270")

  FlickRaw.url_b(info) # => "https://farm3.static.flickr.com/2485/3839885270_6fb8b54e06_b.jpg"



=== url_profile



  info = flickr.photos.getInfo(:photo_id => "3839885270")

  FlickRaw.url_profile(info) # => "https://www.flickr.com/people/41650587@N02/"



=== url_photopage



  info = flickr.photos.getInfo(:photo_id => "3839885270")

  FlickRaw.url_photopage(info) # => "https://www.flickr.com/photos/41650587@N02/3839885270"



=== url_photoset, url_photosets



  info = flickr.photos.getInfo(:photo_id => "3839885270")

  FlickRaw.url_photosets(info) # => "https://www.flickr.com/photos/41650587@N02/sets/"



=== url_short, url_short_m, url_short_s, url_short_t



  info = flickr.photos.getInfo(:photo_id => "3839885270")

  FlickRaw.url_short(info) # => "https://flic.kr/p/6Rjq7s"



=== url_photostream



  info = flickr.photos.getInfo(:photo_id => "3839885270")

  FlickRaw.url_photostream(info) # => "https://www.flickr.com/photos/41650587@N02/"



See the _examples_ directory to find more examples.



== Cached version



You can use



  require 'flickraw-cached'



instead of



  require 'flickraw'



This way it it doesn't fetch available flickr methods each time it is loaded.

The flickraw-cached gem is on rubygems.org and should be up-to-date with regard to flickr api most of the time.