Skip to content
Amazon Product Advertising API client
Branch: master
Clone or download

Latest commit


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Fix coverage in build script Jan 8, 2020
lib Cut 3.3.0 Jan 26, 2020
test Measure coverage Jan 8, 2020
.gitignore Measure coverage Jan 8, 2020
.rubocop.yml Split Rubocop config Oct 28, 2019
.rubocop_todo.yml Fix Rubocop warning Jan 26, 2020 Fix link in CHANGELOG Jan 26, 2020
Gemfile Bump min Ruby version to 2.3 Apr 14, 2018
LICENSE Update and clean up Sep 4, 2016 Fix typo Feb 13, 2020
Rakefile Document with yard Oct 30, 2019
vacuum.gemspec Pin simplecov Feb 13, 2020


Build Maintainability Test Coverage

Vacuum is a Ruby wrapper to Amazon Product Advertising API 5.0. The API provides programmatic access to query product information on the Amazon marketplaces.

Cart Form functionality is not covered by this gem but is a primary focus on carriage gem

You need to register first to use the API.



Getting Started

Create a request with your marketplace credentials. Set the marketplace by passing its two-letter country code.

request = 'US',
                     access_key: '<ACCESS_KEY>',
                     secret_key: '<SECRET_KEY>',
                     partner_tag: '<PARTNER_TAG>')

You can now access the API using the available operations.

response = request.search_items(title: 'lean startup')
puts response.to_h

Create a persistent connection to make multiple requests.



Refer to the API docs for more detailed information.


Given a BrowseNodeId, the GetBrowseNodes operation returns details about the specified browse node, like name, children and ancestors, depending on the resources specified in the request. The names and browse node IDs of the children and ancestor browse nodes are also returned. GetBrowseNodes enables you to traverse the browse node hierarchy to find a browse node.

  browse_node_ids: ['283155', '3040'],
  resources: ['BrowseNodes.Ancestor', 'BrowseNodes.Children']


Given an Item identifier, the GetItems operation returns the item attributes, based on the resources specified in the request.

  item_ids: ['B0199980K4', 'B000HZD168', 'B01180YUXS', 'B00BKQTA4A'],
  resources: ['Images.Primary.Small', 'ItemInfo.Title', 'ItemInfo.Features',
              'Offers.Summaries.HighestPrice' , 'ParentASIN']


Given an ASIN, the GetVariations operation returns a set of items that are the same product, but differ according to a consistent theme, for example size and color. These items which differ according to a consistent theme are called variations. A variation is a child ASIN. The parent ASIN is an abstraction of the children items. For example, a shirt is a parent ASIN and parent ASINs cannot be sold. A child ASIN would be a blue shirt, size 16, sold by MyApparelStore. This child ASIN is one of potentially many variations. The ways in which variations differ are called dimensions.

  asin: 'B00422MCUS',
  resources: ['ItemInfo.Title', 'VariationSummary.Price.HighestPrice',


The SearchItems operation searches for items on Amazon based on a search query. The API returns up to ten items per search request.

request.search_items(keywords: 'harry potter')


Consume a response by parsing it into a Ruby hash.


You can also #dig into this hash.

response.dig('ItemsResult', 'Items')


In addition to the response payload, the following attributes may help you introspect an executed request.

operation = request.operation

Bring your parser

You can extend Vacuum with a custom parser. Just swap the original with a class or module that responds to .parse.

response.parser = MyParser

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


If you are using VCR to test an app that accesses the API, you can use the custom VCR matcher of Vacuum to stub requests.

require 'vacuum/matcher'

# in your test
                    match_requests_on: [Vacuum::Matcher])

In RSpec, consider using custom metadata.

require 'vacuum/matcher'

RSpec.configure do |config|
  config.around do |example|
    if example.metadata[:paapi]
      metadata = example.metadata[:paapi]
      metadata = {} if metadata == true
      example.metadata[:vcr] = metadata.merge(
        match_requests_on: [Vacuum::Matcher]

# in your test
it 'queries Amazon', :paapi do


Clone the repo and install dependencies. Tests should pass as-is.

bundle exec rake

By default, all requests are stubbed. Use the RECORD env var to record new interactions.

bundle exec RECORD=true rake

You can also run tests against live data.

bundle exec LIVE=true rake

In either case, add actual API credentials to a locales.yml file under test.

Getting Help

You can’t perform that action at this time.