Vacuum
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.
You need to register first to use the API.
Usage
Getting Started
Create a request with your marketplace credentials. Set the marketplace by passing its two-letter country code.
“by request = Vacuum.new(marketplace: ‘US’, access_key: ‘
Maruku could not parse this XML/HTML:
<ACCESS_KEY>',
secret_key: '<SECRET_KEY>',
partner_tag: '<PARTNER_TAG>')
“
You can now access the API using the available operations.
“by response = request.search_items(title: ‘lean startup’) puts response.to_h
“
Create a persistent connection to make multiple requests.
“by 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.
“by 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.
“by 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.
“by 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.
“by request.search_items(keywords: ‘harry potter’)
“
Response
Consume a response by parsing it into a Ruby hash.
“by response.to_h
“
You can also #dig
into this hash.
“by response.dig(‘ItemsResult’, ‘Items’)
“
Troubleshooting
In addition to the response payload, the following attributes may help you introspect an executed request.
“by operation = request.operation operation.body operation.headers operation.url
“
Bring your parser
You can extend Vacuum with a custom parser. Just swap the original with a class or module that responds to .parse
.
“by 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.
“by require ‘vacuum/matcher’
in your test
VCR.insert_cassette(‘cassette_name’, match_requests_on: [Vacuum::Matcher])
“
In RSpec, consider using custom metadata.
“by 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] ) end
example.run
end end
in your test
it ‘queries Amazon’, :paapi do end
“
Development
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.
“ell bundle exec LIVE=true rake
“
In either case, add actual API credentials to a locales.yml
file under test
.
Getting Help
- Ask specific questions about the API on the Amazon forum.
- Report bugs and discuss potential features in GitHub issues.