Amazon.com offers a tremendous amount of web services to developers looking to display their products. They benefit from this because developers make all sorts of cool apps for browsing Amazon. For example, nifty 3D Flash experience CoolIris (formerly known as ‘PicLens’) added Amazon functionality to their product. It’s a win-win for developers and Amazon because it drives traffic to the site while paying developers referral fees.

If you’re a Rails developer looking to tap into Amazon’s massive warehouse of product data, you’re in luck. Pluit Solutions has released the amazon-ecs gem exactly for this purpose. It’s as easy to install as:

gem install amazon-ecs

If that doesn’t work for you, you can always  download it from GitHub then install it locally. Or you can clone it at this URL: git://github.com/jugend/amazon-ecs.git

It’s pretty straightforward to set up. The first thing you’ll need to do is get an Amazon Web Services account if you don’t already have one. You can sign up for AWS here.

You’ll need to know your developer token to connect to AWS. They recently made it so you need to specify a secret token as well. It would be something like this in your /config/environment.rb file:

# Be sure to restart your server when you modify this file

# Specifies gem version of Rails to use when vendor/rails is not present
RAILS_GEM_VERSION = '2.3.2' unless defined? RAILS_GEM_VERSION

# Bootstrap the Rails environment, frameworks, and default configuration
require File.join(File.dirname(__FILE__), 'boot')

Rails::Initializer.run do |config|
  config.gem "amazon-ecs", :lib => "amazon/ecs"
  config.time_zone = 'UTC'
  config.frameworks -= [ :active_record ]
end

require 'rubygems'
require 'amazon/ecs'
Amazon::Ecs.options = {:aWS_access_key_id => '************************', :aWS_secret_key => '**********************'}

Just replace the asterisks with your actual AWS public and private keys and you’re set!

Say you want to run a search at the /amazon/ controller’s index action. Let’s generate the controller now:

ruby script/generate controller Amazon

Now in the /app/controllers/amazon_controller.rb file you can define the index action like so:

class AmazonController < ApplicationController
  def index
  end
end

This is where we’ll be putting the service call to AWS to get our data back.

The next step is to add in a hard coded search query. You can make this based on user input later, but for now, let’s just search for ‘Ghostbusters’ and see what we get back.

class AmazonController < ApplicationController
  def index
    query = params[:q]
    page = params[:p]
    @results = Amazon::Ecs.item_search('Ghostbusters', :response_group => 'Medium', :search_index => 'DVD', :item_page => page).items
   end
end

To display the data, we’ll need to make a view for it. Let’s create a new file in /views/amazon called index.html.erb.

The view can look like this:

  (
    {
    results:
      [
        <% @results.each_with_index do |result, i| %>
          {
            title: "<%=h result.get('title') %>",
            detailpageurl: "<%=h result.get('detailpageurl') %>",
            imageurl: "<%=h result.get('mediumimage/url') %>",
            largeimageurl: "<%=h result.get('largeimage/url') %>"
          }<% if i != @results.length%>,<% end %>
        <% end %>
      ]
    }
  )

What’s that, you might ask? It’s just simple JSON actually. We get the data back as pure Ruby objects but for Ajax applications it’s much easier to work with as JSON. You can just as easily make it HTML, but I thought you might want to see the data displayed in JSON first.

Fire up the Ruby server with a ruby script/server call and hit up localhost:3000/Amazon in a browser. You should see a JSON response with a bunch of data pertaining to our query, namely, the movie Ghostbusters.

If you were to display this data as images and links on a page, you could do something like this:

<% @results.each_with_index do |result, i| %>
	<%= content_tag :li, link_to(image_tag(result.get('mediumimage/url'), {:alt => result.get('title')}), result.get('detailpageurl')) %>
<% end %>

If you change the view to be HTML it should render all of the images inside of li elements in the page. The thing is, it’s still always displaying Ghostbusters data. Now we can make it pull in from a query string so it dynamically displays data instead:

class AmazonController < ApplicationController
  def index
    query = params[:q]
    @results = Amazon::Ecs.item_search(query, :response_group => 'Medium', :search_index => 'DVD', :item_page => page).items
   end
end

Now if you go to localhost:3000/amazon?q=2001+a+space+odyssey you should see results pertaining to that masterpiece instead.

And next we can even add a page specification:

class AmazonController < ApplicationController
  def index
    query = params[:q]
    page = params[:p]
    @results = Amazon::Ecs.item_search(query, :response_group => 'Medium', :search_index => 'DVD', :item_page => page).items
   end
end

At this point you can get more than one page of results by specifying the q parameter, e.g.: localhost:3000/amazon?q=2001+a+space+odyssey&p=2 returns results 11-20.

It’s hard coded to searching in ‘DVD’ right now. If we change it like so we can search everything:

class AmazonController < ApplicationController
  def index
    query = params[:q]
    page = params[:p]
    @results = Amazon::Ecs.item_search(query, :response_group => 'Medium', :item_page => page).items
   end
end

I just removed the :search_index specification in the service call. It’s the same thing as specifying :search_index => 'All' so you can do that instead if you wish.

Valid search indexes are:

 	%w[ All Apparel Automotive Baby Beauty Blended Books Classical DigitalMusic DVD Electronics ForeignBooks GourmetFood Grocery HealthPersonalCare Hobbies HomeGarden HomeImprovement Industrial Jewelry KindleStore Kitchen Magazines Merchants Miscellaneous MP3Downloads Music MusicalInstruments MusicTracks OfficeProducts OutdoorLiving PCHardware PetSupplies Photo Shoes SilverMerchants Software SoftwareVideoGames SportingGoods Tools Toys UnboxVideo VHS Video VideoGames Watches Wireless WirelessAccessories ]

Enjoy and best of luck with your Amazon app!