Skip to content
Amazon Product Advertising API client
Branch: master
Clone or download
Latest commit d3a4b96 Nov 13, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Spring cleaning May 31, 2018
examples Add more examples Nov 13, 2018
gemfiles Spring cleaning May 31, 2018
lib Release 2.2.0 Nov 13, 2018
test Turkey returns unauthorised as 400 Nov 13, 2018
.gitignore Some cleanup Aug 5, 2017
.rubocop.yml Spring cleaning May 31, 2018
.travis.yml Bump min Ruby version to 2.3 Apr 14, 2018
Appraisals Spring cleaning May 31, 2018
Gemfile Bump min Ruby version to 2.3 Apr 14, 2018
LICENSE Update and clean up Sep 4, 2016
README.md Improve README Nov 13, 2018
Rakefile Bump min Ruby version to 2.3 Apr 14, 2018
vacuum.gemspec Use pry in development Nov 13, 2018

README.md

Vacuum

Travis

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

vacuum

Usage

Refer to the API docs as necessary.

Prerequisite

You must register as an affiliate to access the 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 #dig into returned Hash:

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.

You can’t perform that action at this time.