What

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

Installing

$ sudo gem install thumbnail

Thumbnail depends on the terrific 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:

1. Signup for an Amazon Web Services account (if you don't yet have one). You can use your existing Amazon user account for this or create a new one.
2. Signup for the Alexa Site Thumbnail Service.
3. 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.

Demonstration of usage

The API provides two actions for accessing site thumbnails: Thumbnail and Redirect and the Thumbnail::Client supports 'em both.

Thumbnail Action

When conducting a thumbnail action (the default), the Client will conduct an api call to fetch the image url(s) from Amazon for immediate download of your thumbnail(s) as follows:

require 'thumbnail'
require 'open-uri'

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

The result will look something like this:

You can also request thumbnails for multiple images simultaneously by passing an array of urls to get. If you do that, you'll have to access the response object differently (see below).

Note: Once you make the get call, and the request to AST goes out, you only have fifteen seconds to use the resulting image url before it expires. This can play havoc with by-hand testing. I recommend that you run something very much like the final line in the example immediately.

The Response Object

Thumbnail action requests will return either a Thumbnail::Response::Success or Thumbnail::Response::Failure object depending on their outcome. Each of these objects offer access to the raw xml response and the Hpricot::Doc object built from parsing it in addtion to the parsed results hash. Further, the [] method has been defined to provide easy access to the parsed results as seen in the example above. Calling to_s on a Failure object will provide a helpful concatenation of the error messages returned by Amazon.

Redirect Action

For a redirect action, the Thumbnail::Client will simply compose and return the image url like so:

require 'thumbnail'

t = Thumbnail::Client.new :access_key_id => YOUR_ACCESS_KEY_ID, 
                          :secret_access_key => YOUR_SECRET_ACCESS_KEY,
                          :action => :redirect
url = t.get("www.twitter.com")

#=> http://ast.amazonaws.com/?Action=Redirect&AWSAccessKeyId=YOUR_ACCESS_KEY_ID
&Signature=sdhfiawrkjw3h9bncoa8ue&Timestamp=2007-06-14T09:09:18.000Z&Url=www.tw
itter.com&Size=Large

The resulting url will redirect to the thumbnail image hosted on s3. This action is perfect for dynamic inclusion of AWS-AST-generated thumbnails in live web pages. Note: this usage of the Thumbnail::Client does not go out over the wire and will not count as a paid api call until you actually request the resulting url with a browser or other user agent.

Default Images

In either action, if you request a thumbnail that is not available, it will be queued for creation within 24 hours and you will not be charged for the request. In the redirect action, you can indicate a Default Image to be returned in this eventuality by including :default_image => 'http://me.com/path/to/my_image.jpg' in the options hash when initializing your Thumbnail::Client. If you don't indicate a default image (or if you're doing a thumbnail action), you'll get the following Alexa "coming soon" default image:

Image Size Options

In both actions, you have a choice between large (201x147 pixels, ~8k) and small (111x82 pixels, ~3k) thumbnails. The Thumbnail::Client defaults to the large size, so if you want the smaller images, you should include :size => :small in your options hash when calling Thumbnail::Client.new (note: there's also an attribute accessor for doing this after initialization). Here are both sizes next to each other for comparison:

Documentation

For more details about using Thumbnail, see the RDoc documentation. To learn more about AWS-AST, see the Alexa Site Thumbnail Service Resource Center.

How to submit patches

Read the 8 steps for fixing other people’s code and then email me.

The trunk repository is svn://rubyforge.org/var/svn/thumbnail/trunk for anonymous access.

License

This code is free to use under the terms of the MIT license.

Contact

Comments are welcome. Send email to Greg Borenstein. Visit my blog: Ideas For Dozens.

This gem was packaged and released with the help of newgem by Dr Nic.
Theme extended from Paul Battley