@@ -2,7 +2,7 @@ == Description -A teeny tiny gem to interface with Flickr photostreams +A small, yet powerful, gem to interface with Flickr photostreams == Installation @@ -22,16 +22,24 @@ Or ... == Usage -Before doing anything, require the library: +To get started, you'll need to grab an API key from Flickr to at least perform any of +the non-authenticated, read-only calls. Head on over to the Flickr site to grab one, I'll +be here when you get back: http://www.flickr.com/services/api/misc.api_keys.html - >> require 'rubygems' - >> require 'fleakr' +Now that you have your key, you can get things rolling with irb and the fleakr gem: + $ irb -r rubygems + >> require 'fleakr' + Then, set your API key (only need to do this once per session): >> Fleakr.api_key = '<your api key here>' - -Find a user by username: + +=== A Brief Tour + +With just an API key, you have the ability to retrieve a substantial amount of data +about users, their photosets, photos, contacts, and groups. Let's start by finding a +user by his username: >> user = Fleakr.user('the decapitator') => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06"> @@ -47,13 +55,18 @@ Once you have a user, you can find his associated sets: => [#<Fleakr::Objects::Set:0x671358 @title="The Decapitator", @description="">, #<Fleakr::Objects::Set:0x66d898 @title="londonpaper hijack", ... +His individual photos: + + >> user.photos.first + => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... > + Or contacts: >> user.contacts.first => #<Fleakr::Objects::User:0x19039bc @username=".schill", @id="12289718@N00", @icon_farm="1", @icon_server="4"> -Or groups if you would like: +Or his groups if you would like: >> user.groups => [#<Fleakr::Objects::Group:0x11f2330 ..., @@ -77,20 +90,59 @@ When accessing a set, you can also grab all the photos that are in that set: >> user.sets.first.photos.first.title => "Untitled1" +=== Photos + +Each photo object contains metadata about a collection of images, each representing different +sizes. Once we have a single photo: + + >> photo = user.photos.first + => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... > + +We can get information about one of the sizes: + + >> photo.small + => #<Fleakr::Objects::Image:0x1768f1c @height="172", @size="Small", @width="240", + @url="http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg", + @page="http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/"> + +Grab the URL for the image itself: + + >> photo.small.url + => "http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg" + +Or grab the URL for its page on the Flickr site: + + >> photo.small.page + => "http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/" + +Other sizes are available (:square, :thumbnail, :small, :medium, :large, :original) and +are accessed in the same way: + + >> photo.original.url + => "http://farm4.static.flickr.com/3250/2924549350_1cf67c2d47_o.jpg" + +=== Saving Images + If a photo interests you, save it down to a directory of your choosing: - >> user.sets.first.photos.first.small.save_to('/tmp') - => #<File:/tmp/2117922283_715587b2cb_m.jpg (closed)> + >> photo.original.save_to('/tmp') + => #<File:/tmp/2924549350_1cf67c2d47_o.jpg (closed)> -If you can't decide on a photo and would rather just save the whole set, specify the target directory -and the size of the images you're interested in: +Similarly, you can save down entire sets. Just specify the target directory and the size +of the images you're interested in: >> user.sets.first.save_to('/tmp', :square) => [#<Fleakr::Objects::Photo:0x1187a1c @secret="715587b2cb" ... + +This creates a subdirectory within the target directory based on the set's name and preserves +the original order of the photos: + >> Dir["/tmp/#{user.sets.first.title}/*.jpg"].map - => ["/tmp/The Decapitator/2117919621_8b2d601bff_s.jpg", - "/tmp/The Decapitator/2117921045_5fb15eff90_s.jpg", - "/tmp/The Decapitator/2117922283_715587b2cb_s.jpg", ... + => ["/tmp/The Decapitator/01_2117922283_715587b2cb_s.jpg", + "/tmp/The Decapitator/02_2125604584_9c09348fd6_s.jpg", + "/tmp/The Decapitator/03_2118696542_8af5763bde_s.jpg", ... ] + +=== Searching If you would prefer to just search photos, you can do that with search text: @@ -116,16 +168,56 @@ Searches can also be scoped to other entities in the system (namely Users and Gr >> user.search('serpent') => [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156", @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">] - -== TODO -* Implement remaining bits of person, photoset, and photo-releated APIs -* Provide a better searching interface -* Lazily load attributes for objects that need to be accessed via secondary API call -* Implement asynchronous file upload / replacement w/ ticket checking +=== Authenticated Calls & Uploads + +While read-only access to the API gets you quite a bit of data, you'll need to generate an +authentication token if you want access to the more powerful features (like uploading your +own photos). + +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 +1. The value for 'Authentication Type' is set to 'Mobile Application' +1. 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 http://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. + +== Roadmap / TODO + +=== 0.4.x + +* Allow passing of parameters to file uploads to allow for access control / naming +* Implement remaining bits of person and photo-related API calls (read-only) * Automatically sign all calls (if we have a secret), authenticate all calls (if we have a token) + +=== 0.5.x + +* Implement asynchronous file upload / replacement w/ ticket checking +* Provide a better searching interface + +=== Future + * Implement save-able search results (e.g. Fleakr.search('ponies').save_to('/path', :medium)) - +* Implement deeper associations for core elements (e.g. tags / etc..) +* Implement write methods for photos & photosets + == License Copyright (c) 2008 Patrick Reagan (reaganpr@gmail.com) README.rdoc @@ -13,7 +13,7 @@ require 'fleakr/core_ext' require 'fleakr/support' require 'fleakr/objects' -# = Fleakr: A teeny tiny gem to interface with Flickr +# = Fleakr: A small, yet powerful, gem to interface with Flickr photostreams # # == Quick Start # lib/fleakr.rb cf10e681de9d456278914f865016fe393bb740fe Patrick Reagan patrick.reagan@viget.com http://github.com/reagent/fleakr/commit/40d146cce54df93ecef5c82263867c1c35d1162d 40d146cce54df93ecef5c82263867c1c35d1162d 2009-01-01T23:14:54-08:00 2009-01-01T23:14:54-08:00 Updated main README file with new features & updated roadmap 6aab711987bb4a71c00a0a225ed2e62b1a481d26 Patrick Reagan patrick.reagan@viget.com