reagent / fleakr

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

fleakr / README.rdoc
raw normal view history
72d796e9 » reagent 2008-12-05 Added RDoc to source files ... 1 = Fleakr
866e035c » reagent 2008-11-02 Initial commit 2
72d796e9 » reagent 2008-12-05 Added RDoc to source files ... 3 == Description
866e035c » reagent 2008-11-02 Initial commit 4
40d146cc » reagent 2009-01-01 Updated main README file wi... 5 A small, yet powerful, gem to interface with Flickr photostreams
866e035c » reagent 2008-11-02 Initial commit 6
72d796e9 » reagent 2008-12-05 Added RDoc to source files ... 7 == Installation
866e035c » reagent 2008-11-02 Initial commit 8
949a07b8 » reagent 2008-12-11 Update documentation 9 === Stable
10
11 sudo gem install fleakr
12
13 === Bleeding Edge
14
eaeea626 » reagent 2008-11-29 Updated example; removed TO... 15 sudo gem install reagent-fleakr --source=http://gems.github.com
caa37c17 » reagent 2008-11-29 Updated README file to incl... 16
17 Or ...
18
19 $ git clone git://github.com/reagent/fleakr.git
20 $ cd fleakr
21 $ rake gem && sudo gem install pkg/fleakr-<version>.gem
866e035c » reagent 2008-11-02 Initial commit 22
72d796e9 » reagent 2008-12-05 Added RDoc to source files ... 23 == Usage
866e035c » reagent 2008-11-02 Initial commit 24
40d146cc » reagent 2009-01-01 Updated main README file wi... 25 To get started, you'll need to grab an API key from Flickr to at least perform any of
26 the non-authenticated, read-only calls. Head on over to the Flickr site to grab one, I'll
27 be here when you get back: http://www.flickr.com/services/api/misc.api_keys.html
caa37c17 » reagent 2008-11-29 Updated README file to incl... 28
40d146cc » reagent 2009-01-01 Updated main README file wi... 29 Now that you have your key, you can get things rolling with irb and the fleakr gem:
caa37c17 » reagent 2008-11-29 Updated README file to incl... 30
40d146cc » reagent 2009-01-01 Updated main README file wi... 31 $ irb -r rubygems
32 >> require 'fleakr'
33
caa37c17 » reagent 2008-11-29 Updated README file to incl... 34 Then, set your API key (only need to do this once per session):
35
0121127a » reagent 2008-12-05 Update README to reflect AP... 36 >> Fleakr.api_key = '<your api key here>'
40d146cc » reagent 2009-01-01 Updated main README file wi... 37
38 === A Brief Tour
39
40 With just an API key, you have the ability to retrieve a substantial amount of data
41 about users, their photosets, photos, contacts, and groups. Let's start by finding a
42 user by his username:
caa37c17 » reagent 2008-11-29 Updated README file to incl... 43
0121127a » reagent 2008-12-05 Update README to reflect AP... 44 >> user = Fleakr.user('the decapitator')
45 => #<Fleakr::Objects::User:0x692648 @username="the decapitator", @id="21775151@N06">
caa37c17 » reagent 2008-11-29 Updated README file to incl... 46
1c69d9ad » reagent 2008-12-02 Updated documentation to re... 47 Or by email:
48
0121127a » reagent 2008-12-05 Update README to reflect AP... 49 >> user = Fleakr.user('user@host.com')
50 => #<Fleakr::Objects::User:0x11f484c @username="bckspcr", @id="84481630@N00">
1c69d9ad » reagent 2008-12-02 Updated documentation to re... 51
52 Once you have a user, you can find his associated sets:
caa37c17 » reagent 2008-11-29 Updated README file to incl... 53
54 >> user.sets
0121127a » reagent 2008-12-05 Update README to reflect AP... 55 => [#<Fleakr::Objects::Set:0x671358 @title="The Decapitator", @description="">,
56 #<Fleakr::Objects::Set:0x66d898 @title="londonpaper hijack", ...
eaeea626 » reagent 2008-11-29 Updated example; removed TO... 57
40d146cc » reagent 2009-01-01 Updated main README file wi... 58 His individual photos:
59
60 >> user.photos.first
61 => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >
62
949a07b8 » reagent 2008-12-11 Update documentation 63 Or contacts:
64
65 >> user.contacts.first
66 => #<Fleakr::Objects::User:0x19039bc @username=".schill",
67 @id="12289718@N00", @icon_farm="1", @icon_server="4">
68
40d146cc » reagent 2009-01-01 Updated main README file wi... 69 Or his groups if you would like:
1614c050 » reagent 2008-11-30 Updated README to reflect g... 70
71 >> user.groups
0121127a » reagent 2008-12-05 Update README to reflect AP... 72 => [#<Fleakr::Objects::Group:0x11f2330 ...,
73 #<Fleakr::Objects::Group:0x11f2308 ...
1614c050 » reagent 2008-11-30 Updated README to reflect g... 74 >> user.groups.first.name
75 => "Rural Decay"
76 >> user.groups.first.id
77 => "14581414@N00"
78
949a07b8 » reagent 2008-12-11 Update documentation 79 Groups also contain photos:
80
431269e9 » reagent 2008-12-11 Correct typo in README docu... 81 >> user.groups.last.photos.first.title
949a07b8 » reagent 2008-12-11 Update documentation 82 => "Welcome To The Machine"
83
1c69d9ad » reagent 2008-12-02 Updated documentation to re... 84 When accessing a set, you can also grab all the photos that are in that set:
11978883 » reagent 2008-11-29 Update examples in document... 85
86 >> user.sets.first
0121127a » reagent 2008-12-05 Update README to reflect AP... 87 => #<Fleakr::Objects::Set:0x1195bbc @title="The Decapitator", @id="72157603480986566", @description="">
11978883 » reagent 2008-11-29 Update examples in document... 88 >> user.sets.first.photos.first
0121127a » reagent 2008-12-05 Update README to reflect AP... 89 => #<Fleakr::Objects::Photo:0x1140108 ... >
11978883 » reagent 2008-11-29 Update examples in document... 90 >> user.sets.first.photos.first.title
91 => "Untitled1"
1c69d9ad » reagent 2008-12-02 Updated documentation to re... 92
40d146cc » reagent 2009-01-01 Updated main README file wi... 93 === Photos
94
95 Each photo object contains metadata about a collection of images, each representing different
96 sizes. Once we have a single photo:
97
98 >> photo = user.photos.first
99 => #<Fleakr::Objects::Photo:0x161b024 @title="\"Be Fabulous\"" ... >
100
101 We can get information about one of the sizes:
102
103 >> photo.small
104 => #<Fleakr::Objects::Image:0x1768f1c @height="172", @size="Small", @width="240",
105 @url="http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg",
106 @page="http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/">
107
108 Grab the URL for the image itself:
109
110 >> photo.small.url
111 => "http://farm4.static.flickr.com/3250/2924549350_cbc1804258_m.jpg"
112
113 Or grab the URL for its page on the Flickr site:
114
115 >> photo.small.page
116 => "http://www.flickr.com/photos/the_decapitator/2924549350/sizes/s/"
117
118 Other sizes are available (:square, :thumbnail, :small, :medium, :large, :original) and
119 are accessed in the same way:
120
121 >> photo.original.url
122 => "http://farm4.static.flickr.com/3250/2924549350_1cf67c2d47_o.jpg"
123
124 === Saving Images
125
1c69d9ad » reagent 2008-12-02 Updated documentation to re... 126 If a photo interests you, save it down to a directory of your choosing:
127
40d146cc » reagent 2009-01-01 Updated main README file wi... 128 >> photo.original.save_to('/tmp')
129 => #<File:/tmp/2924549350_1cf67c2d47_o.jpg (closed)>
1c69d9ad » reagent 2008-12-02 Updated documentation to re... 130
40d146cc » reagent 2009-01-01 Updated main README file wi... 131 Similarly, you can save down entire sets. Just specify the target directory and the size
132 of the images you're interested in:
1c69d9ad » reagent 2008-12-02 Updated documentation to re... 133
134 >> user.sets.first.save_to('/tmp', :square)
0121127a » reagent 2008-12-05 Update README to reflect AP... 135 => [#<Fleakr::Objects::Photo:0x1187a1c @secret="715587b2cb" ...
40d146cc » reagent 2009-01-01 Updated main README file wi... 136
137 This creates a subdirectory within the target directory based on the set's name and preserves
138 the original order of the photos:
139
1c69d9ad » reagent 2008-12-02 Updated documentation to re... 140 >> Dir["/tmp/#{user.sets.first.title}/*.jpg"].map
40d146cc » reagent 2009-01-01 Updated main README file wi... 141 => ["/tmp/The Decapitator/01_2117922283_715587b2cb_s.jpg",
142 "/tmp/The Decapitator/02_2125604584_9c09348fd6_s.jpg",
143 "/tmp/The Decapitator/03_2118696542_8af5763bde_s.jpg", ... ]
144
145 === Searching
11978883 » reagent 2008-11-29 Update examples in document... 146
ac1e3263 » reagent 2008-12-02 Updated docs to reflect sea... 147 If you would prefer to just search photos, you can do that with search text:
237efab4 » reagent 2008-12-01 Added documentation for sea... 148
949a07b8 » reagent 2008-12-11 Update documentation 149 >> photos = Fleakr.search('ponies!!')
0121127a » reagent 2008-12-05 Update README to reflect AP... 150 => [#<Fleakr::Objects::Photo:0x11f4e64 @title="hiroshima atomic garden", @id="3078234390">,
151 #<Fleakr::Objects::Photo:0x11f4928 @title="PONYLOV", @id="3077360853">, ...
949a07b8 » reagent 2008-12-11 Update documentation 152 >> photos.first.title
ac1e3263 » reagent 2008-12-02 Updated docs to reflect sea... 153 => "hiroshima atomic garden"
154
155 You can also search based on tags:
156
949a07b8 » reagent 2008-12-11 Update documentation 157 >> photos = Fleakr.search(:tags => 'macro')
158 >> photos.first.title
9c782f33 » reagent 2008-12-01 Fixed README formatting 159 => "Demure"
949a07b8 » reagent 2008-12-11 Update documentation 160 >> photos.first.id
9c782f33 » reagent 2008-12-01 Fixed README formatting 161 => "3076049945"
237efab4 » reagent 2008-12-01 Added documentation for sea... 162
949a07b8 » reagent 2008-12-11 Update documentation 163 Searches can also be scoped to other entities in the system (namely Users and Groups):
164
165 >> user.groups.first.search('awesome')
166 => [#<Fleakr::Objects::Photo:0x18cb4cc @server_id="2012", @id="2181921273",
167 @farm_id="3", @title="", @secret="634eda7521">, ...
168 >> user.search('serpent')
169 => [#<Fleakr::Objects::Photo:0x18a6960 @server_id="41", @id="81370156",
170 @farm_id="1", @title="Clear and Serpent Danger", @secret="013091582a">]
866e035c » reagent 2008-11-02 Initial commit 171
40d146cc » reagent 2009-01-01 Updated main README file wi... 172 === Authenticated Calls & Uploads
173
174 While read-only access to the API gets you quite a bit of data, you'll need to generate an
175 authentication token if you want access to the more powerful features (like uploading your
176 own photos).
177
178 Assuming you've already applied for a key, go back and make sure you have the right settings
179 to get your auth token. Click on the 'Edit key details' link and ensure that:
180
181 1. Your application description and notes are up-to-date
182 1. The value for 'Authentication Type' is set to 'Mobile Application'
183 1. The value for 'Mobile Permissions' is set to either 'write' or 'delete'
184
185 Once this is set, you'll see your Authentication URL on the key details page (it will look
186 something like http://www.flickr.com/auth-534525246245). Paste this URL into your browser and
187 confirm access to get your mini-token. Now you're ready to make authenticated requests:
188
189 require 'rubygems'
190 require 'fleakr'
191
192 Fleakr.api_key = 'ABC123'
193 Fleakr.shared_secret = 'sekrit' # Available with your key details on the Flickr site
194 Fleakr.mini_token = '362-133-214'
195
196 Fleakr.upload('/path/to/my/photo.jpg')
197 Fleakr.token.value # => "34132412341235-12341234ef34"
198
199 Once you use the mini-token once, it is no longer available. To use the generated auth_token
200 for future requests, just set Fleakr.auth_token to the generated value.
201
202 == Roadmap / TODO
203
204 === 0.4.x
205
206 * Allow passing of parameters to file uploads to allow for access control / naming
207 * Implement remaining bits of person and photo-related API calls (read-only)
7db81a15 » reagent 2008-12-31 Update TODOs 208 * Automatically sign all calls (if we have a secret), authenticate all calls (if we have a token)
40d146cc » reagent 2009-01-01 Updated main README file wi... 209
210 === 0.5.x
211
212 * Implement asynchronous file upload / replacement w/ ticket checking
213 * Provide a better searching interface
214
215 === Future
216
7db81a15 » reagent 2008-12-31 Update TODOs 217 * Implement save-able search results (e.g. Fleakr.search('ponies').save_to('/path', :medium))
40d146cc » reagent 2009-01-01 Updated main README file wi... 218 * Implement deeper associations for core elements (e.g. tags / etc..)
219 * Implement write methods for photos & photosets
220
72d796e9 » reagent 2008-12-05 Added RDoc to source files ... 221 == License
866e035c » reagent 2008-11-02 Initial commit 222
223 Copyright (c) 2008 Patrick Reagan (reaganpr@gmail.com)
224
225 Permission is hereby granted, free of charge, to any person
226 obtaining a copy of this software and associated documentation
227 files (the "Software"), to deal in the Software without
228 restriction, including without limitation the rights to use,
229 copy, modify, merge, publish, distribute, sublicense, and/or sell
230 copies of the Software, and to permit persons to whom the
231 Software is furnished to do so, subject to the following
232 conditions:
233
234 The above copyright notice and this permission notice shall be
235 included in all copies or substantial portions of the Software.
236
237 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
238 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
239 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
240 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
241 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
242 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
243 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
244 OTHER DEALINGS IN THE SOFTWARE.