Vacuum

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

Usage

Prerequisite

You must register as an affiliate to access the Product Advertising API. Amazon will issue your AWS credentials when you register.

Setup

Create a request:

request = Vacuum.new

The locale will default to the US. To use another locale, reference its two-letter country code:

request = Vacuum.new('GB')

Configure the request credentials:

request.configure(
  aws_access_key_id: 'key',
  aws_secret_access_key: 'secret',
  associate_tag: 'tag'
)

You can omit the above if you set your key and secret as environment variables:

export AWS_ACCESS_KEY_ID=key
export AWS_SECRET_ACCESS_KEY=secret

You will still need to set an associate tag:

request.associate_tag = 'tag'

Provided you are looking to earn commission, you have to register independently with each locale you query. Otherwise, you may reuse any dummy associate tag.

The API version defaults to 2013-08-01. To use another version, reference its date string:

request.version = '2011-08-01'

Request

Browse Node Lookup

BrowseNodeLookup returns a specified browse node’s name and ancestors:

response = request.browse_node_lookup(
  query: {
    'BrowseNodeId' => 123
  }
)

Cart Operations

The CartCreate operation creates a remote shopping cart:

response = request.cart_create(
  query: {
    'HMAC' => 'secret',
    'Item.1.OfferListingId' => '123',
    'Item.1.Quantity' => 1
  }
)

The CartAdd operation adds items to an existing remote shopping cart:

response = request.cart_add(
  query: {
    'CartId' => '123',
    'HMAC' => 'secret',
    'Item.1.OfferListingId' => '123',
    'Item.1.Quantity' => 1
  }
)

The CartClear operation removes all of the items in a remote shopping cart:

response = request.cart_clear(
  query: {
    'CartId' => '123',
    'HMAC' => 'secret'
  }
)

The CartGet operation retrieves the IDs, quantities, and prices of the items, including SavedForLater ones, in a remote shopping cart:

response = request.cart_get(
  query: {
    'CartId' => '123',
    'HMAC' => 'secret',
    'CartItemId' => '123'
  }
)

Item Lookup

The ItemLookup operation returns some or all of the attributes of an item, depending on the response group specified in the request. By default, the operation returns an item’s ASIN, manufacturer, product group, and title.

response = request.item_lookup(
  query: {
    'ItemId' => '0679753354'
  }
)

Item Search

The ItemSearch operation returns items that satisfy the search criteria, including one or more search indices.

response = request.item_search(
  query: {
    'Keywords' => 'Architecture',
    'SearchIndex' => 'Books'
  }
)

Similarity Lookup

The SimilarityLookup operation returns up to ten products per page that are similar to one or more items specified in the request. This operation is typically used to pique a customer’s interest in buying something similar to what they’ve already ordered.

response = request.similarity_lookup(
  query: {
    'ItemId' => '0679753354'
  }
)

Configuring a request

Vacuum wraps Excon. Use the latter's API to tweak your request.

For example, to use a persistent connection:

response = request.item_search(
  query: {
    'ItemId' => '0679753354'
  },
  persistent: true
)

Response

The quick and dirty way to consume a response is to parse into a Ruby hash:

response.to_h

You can also use the #dig polyfill:

response.dig('ItemSearchResponse', 'Items', 'Item')

In production, you may prefer to use a custom parser to do some XML heavy-lifting:

class MyParser
  # A parser has to respond to this.
  def self.parse(body)
    new(body)
  end

  def initialize(body)
    @body = body
  end

  # Implement parser here.
end

response.parser = MyParser
response.parse

If no custom parser is set, Vacuum::Response#parse delegates to #to_h.

benrudolph/vacuum