Vacuum
Vacuum is a fast, light-weight Ruby wrapper to the Amazon Product Advertising API.
Usage
Prerequisite
You must register as an affiliate to access the Product Advertising API. Amazon will issue your AWS credentials when you register.
Setup
Create a request:
request = Vacuum.new
The locale will default to the US. To use another locale, reference its two-letter country code:
request = Vacuum.new('GB')
Configure the request credentials:
request.configure(
aws_access_key_id: 'key',
aws_secret_access_key: 'secret',
associate_tag: 'tag'
)
You can omit the above if you set your key and secret as environment variables:
export AWS_ACCESS_KEY_ID=key
export AWS_SECRET_ACCESS_KEY=secret
You will still need to set an associate tag:
request.associate_tag = 'tag'
Provided you are looking to earn commission, you have to register independently with each locale you query. Otherwise, you may reuse any dummy associate tag.
The API version defaults to 2013-08-01
. To use another version, reference its date string:
request.version = '2011-08-01'
Request
Browse Node Lookup
BrowseNodeLookup returns a specified browse node’s name and ancestors:
response = request.browse_node_lookup(
query: {
'BrowseNodeId' => 123
}
)
Cart Operations
The CartCreate operation creates a remote shopping cart:
response = request.cart_create(
query: {
'HMAC' => 'secret',
'Item.1.OfferListingId' => '123',
'Item.1.Quantity' => 1
}
)
The CartAdd operation adds items to an existing remote shopping cart:
response = request.cart_add(
query: {
'CartId' => '123',
'HMAC' => 'secret',
'Item.1.OfferListingId' => '123',
'Item.1.Quantity' => 1
}
)
The CartClear operation removes all of the items in a remote shopping cart:
response = request.cart_clear(
query: {
'CartId' => '123',
'HMAC' => 'secret'
}
)
The CartGet operation retrieves the IDs, quantities, and prices of the items, including SavedForLater ones, in a remote shopping cart:
response = request.cart_get(
query: {
'CartId' => '123',
'HMAC' => 'secret',
'CartItemId' => '123'
}
)
Item Lookup
The ItemLookup operation returns some or all of the attributes of an item, depending on the response group specified in the request. By default, the operation returns an item’s ASIN, manufacturer, product group, and title.
response = request.item_lookup(
query: {
'ItemId' => '0679753354'
}
)
Item Search
The ItemSearch operation returns items that satisfy the search criteria, including one or more search indices.
response = request.item_search(
query: {
'Keywords' => 'Architecture',
'SearchIndex' => 'Books'
}
)
Similarity Lookup
The SimilarityLookup operation returns up to ten products per page that are similar to one or more items specified in the request. This operation is typically used to pique a customer’s interest in buying something similar to what they’ve already ordered.
response = request.similarity_lookup(
query: {
'ItemId' => '0679753354'
}
)
Configuring a request
Vacuum wraps Excon. Use the latter's API to tweak your request.
For example, to use a persistent connection:
response = request.item_search(
query: {
'ItemId' => '0679753354'
},
persistent: true
)
Response
The quick and dirty way to consume a response is to parse into a Ruby hash:
response.to_h
You can also use the #dig
polyfill:
response.dig('ItemSearchResponse', 'Items', 'Item')
In production, you may prefer to use a custom parser to do some XML heavy-lifting:
class MyParser
# A parser has to respond to this.
def self.parse(body)
new(body)
end
def initialize(body)
@body = body
end
# Implement parser here.
end
response.parser = MyParser
response.parse
If no custom parser is set, Vacuum::Response#parse
delegates to #to_h
.