Build Status

Vacuum is a fast, light-weight Ruby wrapper to the Amazon Product Advertising API.




Set up a request:

req =

The locale defaults to the US. To use another locale, instantiate with its two-letter country code:

req ='GB')

Configure the request credentials:

    aws_access_key_id:     'key',
    aws_secret_access_key: 'secret',
    associate_tag:         'tag'

Alternatively, set the key and secret as environment variables globally:

export AWS_ACCESS_KEY_ID=key

You will still need to set a distinct associate tag for each locale:

req.associate_tag = 'tag'


Set up your parameters and make a request:

params = {
  'SearchIndex' => 'Books',
  'Keywords'    => 'Architecture'
res = req.item_search(query: params)

The above executes an item search operation. The names of available methods derive from the operations listed in the API docs and include browse_node_lookup, cart_add, cart_clear, cart_create, cart_get, cart_modify, item_lookup, item_search, and similarity_lookup.

Vacuum uses Excon as HTTP client. Check the Excon API for ways to tweak your request:

res = req.item_search(query: params, persistent: true)


The quickest way to consume a response is to parse it into a Ruby hash:


Vacuum uses MultiXml, which will work with a number of popular XML libraries. If working in MRI, you may want to use Ox.

You can also pass the response body into your own parser for some custom XML heavy-lifting: