Need help with vacuum?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

hakanensari
536 Stars 76 Forks MIT License 1.1K Commits 1 Opened issues

Description

Amazon Product Advertising API client

Services available

!
?

Need anything else?

Contributors list

Vacuum

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.

vacuum

Usage

Getting Started

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

request = Vacuum.new(marketplace: 'US',
                     access_key: '',
                     secret_key: '',
                     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.

request.persistent

Operations

Refer to the API docs for more detailed information.

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 API returns up to ten items per search request.
request.search_items(keywords: 'harry potter')

Response

Consume a response by parsing it into a Ruby hash.

response.to_h

You can also

#dig
into this hash.
response.dig('ItemsResult', 'Items')

Logging

Write requests and reponses to a logger using the logging feature of the HTTP gem under the hood:

require 'logger'

logger = Logger.new(STDOUT) request.use(logging: {logger: logger})

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
response.parse

If no custom parser is set,

Vacuum::Response#parse
delegates to
#to_h
.

VCR

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

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

In RSpec, use the

:paapi
metadata.
require 'vacuum/matcher'

in your test

it 'queries Amazon', :paapi do end

Development

Clone the repo and install dependencies.

bundle install

Tests and Rubocop should now pass as-is.

bundle exec rake

By default, the tests stub requests. Use the

RECORD
env var to record new interactions.
RECORD=true bundle exec rake test

You can set the

LIVE
env var to run all tests against live data.
LIVE=true bundle exec rake test

In either case, add actual API credentials to a

locales.yml
file under

test
.

Getting Help

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.