Vacuum

Vacuum is a Ruby wrapper to the Amazon Creators API. The API provides programmatic access to product information on the Amazon marketplaces.

Create a client with your credentials.

client = Vacuum.new(
  credential_id: "YOUR_CREDENTIAL_ID",
  credential_secret: "YOUR_CREDENTIAL_SECRET",
  version: "2.1"
)

The client handles authentication automatically and caches access tokens for one hour.

You can now access the API using the available operations.

response = client.search_items(
  marketplace: "www.amazon.com",
  partner_tag: "yourtag-20",
  keywords: "lean startup"
)
response.parse

The version determines which authentication endpoint to use. Versions 2.x use Amazon Cognito; versions 3.x use Login with Amazon (LwA).

Each operation requires marketplace (e.g., "www.amazon.com") and partner_tag parameters.

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.

client.get_browse_nodes(
  marketplace: "www.amazon.com",
  partner_tag: "yourtag-20",
  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.

client.get_items(
  marketplace: "www.amazon.com",
  partner_tag: "yourtag-20",
  item_ids: ["B0199980K4", "B000HZD168"],
  resources: ["images.primary.small", "itemInfo.title", "itemInfo.features",
              "offersV2.listings.price", "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.

client.get_variations(
  marketplace: "www.amazon.com",
  partner_tag: "yourtag-20",
  asin: "B00422MCUS",
  resources: ["itemInfo.title", "variationSummary.price.highestPrice",
              "variationSummary.price.lowestPrice",
              "variationSummary.variationDimension"]
)

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

client.search_items(
  marketplace: "www.amazon.com",
  partner_tag: "yourtag-20",
  keywords: "harry potter"
)

Parse the response body into a hash.

response.parse.dig("searchResult", "items")

By default, each client instance caches its own access token. In multi-process environments like Rails, you can share the token across processes by providing a cache store.

client = Vacuum.new(
  credential_id: "YOUR_CREDENTIAL_ID",
  credential_secret: "YOUR_CREDENTIAL_SECRET",
  version: "2.1",
  cache: Rails.cache
)

The cache must respond to fetch(key, expires_in:, &block).

Clone the repo and install dependencies.

bundle install

Run tests and Rubocop.

bundle exec rake

To run API tests, copy spec/credentials.yml.example to spec/credentials.yml and fill in your credentials.

Amazon is a $250 billion dollar company that reacts to you buying a vacuum by going THIS GUY LOVES BUYING VACUUMS HERE ARE SOME MORE VACUUMS

— @kibblesmith