thumbnail

= THUMBNAIL

A Ruby wrapper for the Amazon Web Services Alexa Site Thumbnail Service REST API, which provides website thumbnail images on demand for a small fee ($0.20/1000).

by Greg Borenstein
thumbnail.rubyforge.org

== Installing

$ sudo gem install thumbnail

Thumbnail depends on the terrific Hpricot (http://code.whytheluckystiff.net/hpricot) XHTML parsing and manipulation library by why the lucky stiff; version 0.5 or better has the necessary powers.

== Registering with Amazon

In order to use the AWS-AST api, you must first complete the following series of bureaucratic tasks:

• Signup for an Amazon Web Services account (if you don't yet have one) by visiting http://aws.amazon.com . You can use your existing Amazon user account for this or create a new one.

• Signup for the Alexa Site Thumbnail Service (http://www.amazon.com/b/ref=sc_fe_c_0_239513011_4/102-1130464-8229719?ie=UTF8&node=236156011&no=239513011&me=A36L942TSJ2AJA)

• Find and note your AWS Access Key Id and your Secret Access Key. You'll need to tell Thumbnail about these for authentication's sake; you should be given them at the end of the signup process.

Registering for both of these accounts is free, payment for the Site Thumbnail Service is based entirely on usage, with no charges for requests for unavailable thumbnails.

== Some Usage Examples

Download a small thumbnail of http://www.craphound.com as a local file called small_crap.jpg:

require 'thumbnail'
require 'open-uri'

t = Thumbnail::Client.new :access_key_id => YOUR_ACCESS_KEY_ID, :secret_access_key => YOUR_SECRET_ACCESS_KEY, :size => :small
url = t.get("www.craphound.com")[:thumbnail][:url]
File.open("small_crap.jpg", "w") { |f| f.write open(url).read }

Write a view helper for use in a Rails application to generate image tags with Amazon redirect urls in your templates. In app/helpers/my_helper.rb:

module MyHelper
  def thumbnail_image(url, size=:large)
    t = Thumbnail::Client.new :access_key_id => AWS_ACCESS_KEY_ID, :secret_access_key => AWS_SECRET_ACCESS_KEY, 
                              :action => :redirect, :size => size
    "<img src=\"#{t.get(url)}\">"
  end
end

which, assuming you'd defined AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in your environment.rb file and required thumbnail somewhere along the line, you'd use in your view like so:

<%= thumbnail_image("www.craphound.com") %>

(Work is underway on a plugin that would make this helper universally available within your app.)

Download large thumbnails for a bunch of sites in one batch with error handling:

require 'thumbnail'
require 'open-uri'

t = Thumbnail::Client.new :access_key_id => YOUR_ACCESS_KEY_ID, :secret_access_key => YOUR_SECRET_ACCESS_KEY
result = t.get(["www.craphound.com", "www.urbanhonking.com", "www.twitter.com"])
if result.is_a? Thumbnail::Response::Success
  result.parsed.each do |r|
    url = r[:thumbnail][:url]
    filename = "#{r[:thumbnail][:request_url].split(".")[1]}.jpg"
    File.open(filename, "w") { |f| f.write open(url).read }
  end
else
  puts "Request failed! #{result}"
end

For a more verbose walkthrough (and an idea of what the thumbnails look like), visit Thumbnail's rubyforge homepage: http://thumbnail.rubyforge.org. For more details on the library's operation, see the spec output in client_spec.txt and response_spec.txt.

== Other Facts of Note

-If a site thumbnail is not available, AWS-AST will return the "not available" image and will not charge for the api call. The actual site thumbnail will be created within 24 hours. The parsed results hash of a Thumbnail::Response::Success object offers programatic access to this via the :exists key.

-Thumbnail urls generated by calls to the api are good for 15 seconds, so run your code that downloads and saves them right away.

== AWS-AST API Docs

http://docs.amazonwebservices.com/AlexaSiteThumbnail/2007-01-01/

== License

Copyright 2007 Greg Borenstein. This code is free to use under the terms of the MIT license.

== Feedback

Got questions? Got Kudos? Email me: [e-mail].