Vacuum

CircleCI

Vacuum is a light-weight Ruby wrapper to Amazon Product Advertising API 5.0. The API provides programmatic access to search and get detailed product information on the Amazon marketplaces.

vacuum

Usage

Vacuum follows the nomenclature of the Product Advertising API. The examples below are based on examples in the Amazon docs.

Getting Started

You need to register as an affiliate and apply for API access on each marketplace you want to query product information.

Create a request with your marketplace credentials, passing the two-letter country code of the marketplace.

request = Vacuum.new(marketplace: 'US',
                     access_key: '<ACCESS_KEY>',
                     secret_key: '<SECRET_KEY>',
                     partner_tag: '<PARTNER_TAG>')

Vacuum uses HTTPI under the hood. You can swap the HTTP library it uses if you prefer an alternative one for speed or introspection.

HTTPI.adapter = :http

Operations

GetBrowseNodes

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.

request.get_browse_nodes(
  browse_node_ids: ['283155', '3040'],
  resources: ['BrowseNodes.Ancestor', 'BrowseNodes.Children']
)

GetItems

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

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

GetVariations

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.

request.get_variations(
  asin: 'B00422MCUS',
  resources: ['ItemInfo.Title', 'VariationSummary.Price.HighestPrice',
              'VariationSummary.Price.LowestPrice',
              'VariationSummary.VariationDimension']
)

SearchItems

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

request.search_items(keywords: 'harry potter')

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 the returned Hash:

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

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

response.parser = MyParser
response.parse

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

VCR Support

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

require 'vacuum/matcher'

VCR.insert_cassette('paapi', match_requests_on: [Vacuum::Matcher])

Testing

Tests should pass as-is once you install dependencies.

bundle exec rake

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

bundle exec RECORD=true rake

You can also run tests against live data.

bundle exec LIVE=true rake

In either case, you will want to add actual API credentials to a locales.yml file in the test directory.

Getting Help