davidntompkins / vacuum

A Ruby wrapper to the Amazon Product Advertising API

Vacuum

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

Usage

Setup

Set up a request:

req = Vacuum.new

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

req = Vacuum.new('GB')

Configure the request credentials:

req.configure(
    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
export AWS_SECRET_ACCESS_KEY=secret

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

req.associate_tag = 'tag'

Request

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)

Response

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

res.to_h

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:

MyParser.new(res.body)