A JSON webservice for Amazon's product catalogue.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 8aa1e0e Apr 20, 2010
Failed to load latest commit information.
lib ... Apr 20, 2010
.gitignore first commit Apr 16, 2010
README.textile Deleted index.html Apr 20, 2010
app.rb Sinatra::Base Apr 20, 2010
config.ru first commit Apr 16, 2010
config.yml first commit Apr 16, 2010
standalone.ru first commit Apr 16, 2010



amazon-json-api is a JSONP-enabled webservice that serves amazon.com’s product catalogue in an easily consumable JSON format.

You can use amazon-json-api to pull data from Amazon’s product catalogue and display it on your site.

The application uses Amazon’s ItemSearch and the amazon-ecs gem behind the scenes to pull in data from Amazon.


You’ll need Sinatra, Rack::Cache, amazon-ecs and ActiveSupport:

gem install sinatra rack-cache activesupport amazon-ecs


Put your Amazon API key and secret in config.yml:

  debug: true
  key: xxx
  secret: xxx

Results are by default cached in memory for 24 hours. You can tweak cache settings in config.yml:

  ttl: 86400
  metastore: heap:/
  entitystore: heap:/
  #metastore: file:/tmp/cache/rack/meta
  #entitystore: file:/tmp/cache/rack/body
  verbose: false


Starting the web server is as easy as executing this command:

$ ./app.rb

Tip: use Phusion Passenger and nginx in a production environment.

How to

All request parameters are forwarded as-is to the Amazon REST-API, which means this request:

Translates to the following ItemSearch query:

Note how the signature, timestamp, and access key are all added automatically.


Search books and return JSON

This URL executes a power search for books having the words python and programming in the title:


The books are sorted by salesrank. Data is returned as JSON.

See the ItemSearch documentation for details.

Search books and return JSONP

The benefit of using JSONP is that you can host the webservice on one domain and use it on as many other domains as you need.

To search for books we use the same URL as the previous one with the addition of a callback parameter, which tells the webservice to return JSONP instead of JSON:

To retrieve the data you would add this code to your HTML:

<script defer="defer" type="text/javascript" src="http://localhost:4567/?response_group=ItemAttributes,Images&search_index=Books&sort=salesrank&power=title:xxx&callback=showBooks"></script>

Or the jQuery equivalent:

    type: 'get',
    url: '/?your query goes here',
    dataType: 'jsonp',
    success: function(books) {

To render the data you would write a JSONP callback method such as this:

 <script type="text/javascript" defer="defer">
  function showBooks(books) {
    $.each(books, function(index, book) {
        var title = book.itemattributes.title;
        var url = book.detailpageurl;
        var image = book.mediumimage.url;
        var height = book.mediumimage.height;
        var width = book.mediumimage.width;

        // Do something smart here

Search the electronics department

This URL searches the electronics department for items containing the keyword “bluray”:

See the full list of search indexes for more options.

That’s it. You can see the webservice in action on this code snippets page.


Christian Hellsten (Aktagon Ltd.)