Operations¶
All functionality of the Amazon Product Advertising API is provided by operations each of which will accept a number of different parameters both required and optional. A special signed URL has to be constructed from which the result of an operation can be retrieved as a XML document.
Building the individual URL can be quite cumbersome when done repeatedly by
hand. That’s the main reason why this module came into being. Any operation
listed in the API documentation can thus be called with call()
.
To look up information on an article, one could for instance call ItemLookup
in the following way:
api.call(Operation='ItemLookup', ItemId='B00008OE6I')
However, this module offers a few convenience methods which can make your life
easier by producing clearer error messages or even paginating over the returned results. For the above call you would simply use
item_lookup()
.
Below is a list of all the operations which are specifically supported in this module.
Lookup and search operations¶
These operations are the heart and soul of the API. With these you can search for products and retreive their data.
-
API.
item_search
(searchindex, **query)¶ Changed in version 2011-08-01: You can only fetch up to 10 result pages (instead of 400).
The
item_search()
operation returns items that satisfy the search criteria, including one or more search indices.item_search()
returns up to ten search results at a time. Whencondition
equals “All,”item_search()
returns up to three offers per condition (if they exist), for example, three new, three used, three refurbished, and three collectible items. Or, for example, if there are no collectible or refurbished offers,item_search()
returns three new and three used offers.Because there are thousands of items in each search index,
item_search()
requires that you specify the value for at least one parameter in addition to a search index. The additional parameter value must reference items within the specified search index. For example, you might specify a browse node (BrowseNode
is anitem_search()
parameter), Harry Potter Books, within the Books product category. You would not get results, for example, if you specified the search index to be Automotive and the browse node to be Harry Potter Books. In this case, the parameter value is not associated with the search index value.The
ItemPage
parameter enables you to return a specified page of results. The maximumItemPage
number that can be returned is 400. An error is returned if you try to access higher numbered pages. If you do not includeItemPage
in your request, the first page will be returned by default. There can be up to ten items per page (see Result pagination for more details).item_search()
is the operation that is used most often in requests. In general, when trying to find an item for sale, you use this operation.Examples:
Use the search index, Toys, and the parameter, Keywords, to return information about all toy rockets sold in by Amazon.
>>> api.item_search('Toys', Keywords='Rocket')
Use a blended search to look through multiple search indices for items that have “Mustang” in their name or description. A blended search looks through multiple search indices at the same time.
>>> api.item_search('Blended', Keywords='Mustang')
Use the Availability parameter to only return shirts that are available:
>>> api.item_search('Apparel', Condition='All', ... Availability='Available', Keywords='Shirt')
Set the search index to
MusicTracks
andKeywords
to the title of a song to find a song title.Use the
BrowseNodes
response group to find the browse node of an item.Use the
Variations
response group and theBrowseNode
parameter to find all of the variations of a parent browse node.
-
API.
item_lookup
(id, [id2, ..., ]**extra)¶ Given an item identifier, the
item_lookup()
operation returns some or all of the item attributes, depending on the response group specified in the request. By default,item_lookup()
returns an item’s ASIN, Manufacturer, ProductGroup, and Title of the item.>>> api = API(locale='uk') >>> result = api.item_lookup('B006H3MIV8') >>> for item in result.Items.Item: ... print '%s (%s) in group %s' % ( ... item.ItemAttributes.Title, item.ASIN) ... Chimes of Freedom: The Songs of Bob Dylan (B006H3MIV8)
item_lookup()
supports many response groups, so you can retrieve many different kinds of product information, called item attributes, including product reviews, variations, similar products, pricing, availability, images of products, accessories, and other information.To look up more than one item at a time, you can pass several identifiers at once.
>>> res = api.item_lookup('B000002O4S', 'B000002O6R', 'B0000014RN')
Note
The parameter support varies by locale used.
Examples:
The following request returns the information associated with ItemId B00008OE6I.
>>> api.item_lookup('B00008OE6I')
The following request returns an offer for a refurbished item that is not sold by Amazon
>>> api.item_lookup('B00008OE6I', ... ResponseGroup='OfferFull', Condition='All')
In the following request, the ItemId is an SKU, which requires that you also specify the IdType.
>>> api.item_lookup([SKU], IdType='SKU')
If you use a UPC as ItemId, you also need to specify SearchIndex and ItemType.
>>> api.item_lookup([UPC], SearchIndex='Books', IdType='UPC')
In the following request, the ItemId is an EAN, which requires that you also specify the SearchIndex and ItemType.
>>> api.item_lookup([EAN], IdType='EAN')
Tips:
Use the
BrowseNodes
response group to find the browse node of an item.Use the
Tracks
response group to find the track, title, and number for each track on each CD in the response.Use the
Similarities
response group to find the ASIN and Title for similar products returned in the response.Use the
Reviews
response group to find reviews written by customers about an item, and the total number of reviews for each item in the response.Use the
OfferSummary
response group to find the number of offer listings and the lowest price for each of the offer listing condition classes, includingNew
,Used
,Collectible
, andRefurbished
.Use the
Accessories
response group to find the a list of accessory product ASINs and Titles for each product in the response that has accessories.The following requests an iframe that contains customer reviews for the specified item.
>>> api.item_lookup('0316067938', ResponseGroup='Reviews', ... TruncateReviewsAt=256, IncludeReviewsSummary=False)
-
API.
similarity_lookup
(id, [id2, ..., ]**extra)¶ The
similarity_lookup()
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.If you specify more than one item,
similarity_lookup()
returns the intersection of similar items each item would return separately. Alternatively, you can use the SimilarityType parameter to return the union of items that are similar to any of the specified items. A maximum of ten similar items are returned; the operation does not return additional pages of similar items. If there are more than ten similar items, running the same request can result in different answers because the ten that are included in the response are picked randomly. The results are picked randomly only when you specify multiple items and the results include more than ten similar items.When you specify multiple items, it is possible for there to be no intersection of similar items. In this case, the operation raises the exception
NoSimilarityForASIN
.This result is very often the case if the items belong to different search indices. The error can occur, however, even when the items share the same search index.
Similarity is a measurement of similar items purchased, that is, customers who bought X also bought Y and Z. It is not a measure, for example, of items viewed, that is, customers who viewed X also viewed Y and Z.
Items returned can be filtered by:
Condition
- Describes the status of an item. Valid values are
All
,New
(default),Used
,Refurbished
orCollectible
. When the Availability parameter is set to “Available,” the Condition parameter cannot be set to “New.”
Examples:
Return items that are similar to a list of items.
>>> api.similarity_lookup('ASIN1', 'ASIN2', 'ASIN3')
This request returns the intersection of the similarities for each ASIN. The response to this request is shown in Response to Sample Request.
Return up to ten items that are similar to any of the ASINs specified.
>>> api.similarity_lookup('ASIN1', 'ASIN2', 'ASIN3', ... SimilarityType='Random')
This request returns the union of items that are similar to all of the ASINs specified. Only ten items can be returned and those are picked randomly from all of the similar items. Repeating the operation could produce different results.
Parameters: ids – One or more ASINs you want to look up. You can specify up to ten Ids.
Amazon als structures their products in categories, so called BrowseNodes, each with its unique ID. You can find a list of these nodes here.
-
API.
browse_node_lookup
(browse_node_id, response_group=None, **params)¶ Given a
browse_node_id
, this method returns the specified browse node’s name, children, and ancestors. The names and browse node IDs of the children and ancestor browse nodes are also returned.browse_node_lookup()
enables you to traverse the browse node hierarchy to find a browse node.As you traverse down the hierarchy, you refine your search and limit the number of items returned. For example, you might traverse the following hierarchy:
Books>Children's Books>Science
, to select out of all the science books offered by Amazon only those that are appropriate for children:>>> api = API(locale='us') >>> node_id = 3207 # Books > Children's Books > Science >>> result = api.browse_node_lookup(node_id) >>> for child in result.BrowseNodes.BrowseNode.Children.BrowseNode: ... print '%s (%sa)' % (child.Name, child.BrowseNodeId) ... Agriculture (3208) Anatomy & Physiology (3209) Astronomy & Space (3210) Biology (3214) Botany (3215) Chemistry (3216) Earth Sciences (3217) Electricity & Electronics (3220) Engineering (16244041) Environment & Ecology (3221) Experiments & Projects (3224) Geography (16244051) Health (3230) Heavy Machinery (3249) How Things Work (3250) Inventions & Inventors (16244711) Light & Sound (16244701) Math (3253) Mystery & Wonders (15356851) Nature (3261) Physics (3283) Social Science (3143) Zoology (3301)
Returning the items associated with children’s science books produces a much more targeted result than a search based at the level of books.
Alternatively, by traversing up the browse node tree, you can determine the root category of an item. You might do that, for example, to return the top seller of the root product category using the
TopSellers
response group in anbrowse_node_lookup()
request:>>> # extract all category roots >>> result = api.item_lookup('031603438X', # Keith Richards: Life ... ResponseGroup='BrowseNodes') >>> root_ids = result.xpath( ... '//aws:BrowseNode[aws:IsCategoryRoot=1]/aws:BrowseNodeId', ... namespaces={'aws': result.nsmap.get(None)}) >>> # TopSellers for first category >>> result = api.browse_node_lookup(root_ids[0], 'TopSellers') >>> for item in result.BrowseNodes.BrowseNode.TopSellers.TopSeller: ... print item.ASIN, item.Title ... B004LLHE62 Ghost in the Polka Dot Bikini (A Ghost of Granny Apples Mystery) B004LROUNG The Litigators B005K0HDGE 11/22/63 [Enhanced eBook] B004W2UBYW Steve Jobs 1419702238 Diary of a Wimpy Kid: Cabin Fever 1451648537 Steve Jobs B003YL4LNY Inheritance (The Inheritance Cycle) 0375856110 Inheritance (The Inheritance Cycle) B005IGVS6Q Unfinished Business B005O548QI Last Breath
You can use
browse_node_lookup()
iteratively to navigate through the browse node hierarchy to reach the node that most appropriately suits your search. Then you can use the browse node ID in anitem_search()
request. This response would be far more targeted than, for example, searching through all of the browse nodes in a search index.A list of BrowseNodes can be found here: http://docs.amazonwebservices.com/AWSECommerceService/latest/DG/index.html?BrowseNodeIDs.html
Parameters: - browse_node_id (positive int) – A positive integer assigned by Amazon that uniquely identifies a product category.
- response_group (str) – Specifies the types of values to return. You can
specify multiple response groups in one request by separating them
with commas. Valid Values are
BrowseNodeInfo
(default),MostGifted
,NewReleases
,MostWishedFor
,TopSellers
. - params – This can be any (or none) of the Common request parameters.
Cart operations¶
Since the Amazon Product Advertising API is all about generating revenue for
Amazon, of course, there is also the possibility to create remote shopping
baskets. The operations below are staight-forward and need little explanation.
You may, however, have a look at the amazonproduct.contrib.cart
module
which provides a generic Cart
class to deal
with the responses from these operations.
-
API.
cart_create
(items, **params)¶ cart_create()
enables you to create a remote shopping cart. A shopping cart is the metaphor used by most e-commerce solutions. It is a temporary data storage structure that resides on Amazon servers. The structure contains the items a customer wants to buy. In Product Advertising API, the shopping cart is considered remote because it is hosted by Amazon servers. In this way, the cart is remote to the vendor’s web site where the customer views and selects the items they want to purchase.Once you add an item to a cart by specifying the item’s ListItemId and ASIN, or
OfferListingId
, the item is assigned aCartItemId
and accessible only by that value. That is, in subsequent requests, an item in a cart cannot be accessed by itsListItemId
andASIN
, orOfferListingId
.CartItemId
is returned bycart_create()
,cart_get()
, andcart_add()
.Because the contents of a cart can change for different reasons, such as item availability, you should not keep a copy of a cart locally. Instead, use the other cart operations to modify the cart contents. For example, to retrieve contents of the cart, which are represented by
CartItemIds
, usecart_get()
.Available products are added as cart items. Unavailable items, for example, items out of stock, discontinued, or future releases, are added as
SaveForLaterItems
. No error is generated. The Amazon database changes regularly. You may find a product with an offer listing ID but by the time the item is added to the cart the product is no longer available. The checkout page in the Order Pipeline clearly lists items that are available and those that areSaveForLaterItems
.It is impossible to create an empty shopping cart. You have to add at least one item to a shopping cart using a single
cart_create()
request. You can add specific quantities (up to 999) of each item.cart_create()
can be used only once in the life cycle of a cart. To modify the contents of the cart, use one of the other cart operations.Carts cannot be deleted. They expire automatically after being unused for 7 days. The lifespan of a cart restarts, however, every time a cart is modified. In this way, a cart can last for more than 7 days. If, for example, on day 6, the customer modifies a cart, the 7 day countdown starts over.
Changed in version 0.2.8: Will raise
ParameterOutOfRange
rather thanValueError
.
-
API.
cart_get
(cart_id, hmac, **params)¶ The
cart_get()
operation enables you to retrieve the IDs, quantities, and prices of all of the items, includingSavedForLater
items in a remote shopping cart.Because the contents of a cart can change for different reasons, such as availability, you should not keep a copy of a cart locally. Instead, use
cart_get()
to retrieve the items in a remote shopping cart.To retrieve the items in a cart, you must specify the cart using the
CartId
andHMAC
values, which are returned in thecart_create()
operation. A value similar toHMAC
,URLEncodedHMAC
, is also returned. This value is the URL encoded version of theHMAC
. This encoding is necessary because some characters, such as+
and/
, cannot be included in a URL. Rather than encoding theHMAC
yourself, use theURLEncodedHMAC
value for the HMAC parameter.cart_get()
does not work after the customer has used thePurchaseURL
to either purchase the items or merge them with the items in their Amazon cart.If the associated
cart_create()
request specified anAssociateTag
, allcart_get()
requests must also include a value forAssociateTag
otherwise the request will fail.
-
API.
cart_add
(cart_id, hmac, items, **params)¶ The
cart_add()
operation enables you to add items to an existing remote shopping cart.cart_add()
can only be used to place a new item in a shopping cart. It cannot be used to increase the quantity of an item already in the cart. If you would like to increase the quantity of an item that is already in the cart, you must use thecart_modify()
operation.You add an item to a cart by specifying the item’s
OfferListingId
, orASIN
andListItemId
. Once in a cart, an item can only be identified by itsCartItemId
. That is, an item in a cart cannot be accessed by its ASIN orOfferListingId
.CartItemId
is returned bycart_create()
,cart_get()
, andcart_add()
.To add items to a cart, you must specify the cart using the
CartId
andHMAC
values, which are returned by thecart_create()
operation.If the associated
cart_create()
request specified an AssociateTag, allcart_add()
requests must also include a value for Associate Tag otherwise the request will fail.Note
Some manufacturers have a minimum advertised price (MAP) that can be displayed on Amazon’s retail web site. In these cases, when performing a Cart operation, the MAP Is returned instead of the actual price. The only way to see the actual price is to add the item to a remote shopping cart and follow the PurchaseURL. The actual price will be the MAP or lower.
Changed in version 0.2.8: Will raise
ParameterOutOfRange
rather thanValueError
.
-
API.
cart_modify
(cart_id, hmac, item_ids, **params)¶ The
cart_modify()
operation enables you to change the quantity of items that are already in a remote shopping cart and move items from the active area of a cart to theSaveForLater
area or the reverse.To modify the number of items in a cart, you must specify the cart using the
CartId
and HMAC values that are returned in thecart_create()
operation. A value similar to HMAC,URLEncodedHMAC
, is also returned. This value is the URL encoded version of the HMAC. This encoding is necessary because some characters, such as+
and/
, cannot be included in a URL. Rather than encoding the HMAC yourself, use theURLEncodedHMAC
value for the HMAC parameter.You can use
cart_modify()
to modify the number of items in a remote shopping cart by setting the value of the Quantity parameter appropriately. You can eliminate an item from a cart by setting the value of the Quantity parameter to zero. Or, you can double the number of a particular item in the cart by doubling its Quantity. You cannot, however, usecart_modify()
to add new items to a cart.If the associated
cart_create()
request specified an AssociateTag, allcart_modify()
requests must also include a value for Associate Tag otherwise the request will fail.Changed in version 0.2.8: Will raise
ParameterOutOfRange
orMissingParameters
rather thanValueError
.
-
API.
cart_clear
(cart_id, hmac, **params)¶ The
cart_clear()
operation enables you to remove all of the items in a remote shopping cart, includingSavedForLater
items. To remove only some of the items in a cart or to reduce the quantity of one or more items, usecart_modify()
.To delete all of the items from a remote shopping cart, you must specify the cart using the
CartId
andHMAC
values, which are returned by thecart_create()
operation. A value similar to theHMAC
,URLEncodedHMAC
, is also returned. This value is the URL encoded version of theHMAC
. This encoding is necessary because some characters, such as+
and/
, cannot be included in a URL. Rather than encoding theHMAC
yourself, use the U``RLEncodedHMAC`` value for the HMAC parameter.cart_clear()
does not work after the customer has used thePurchaseURL
to either purchase the items or merge them with the items in their Amazon cart.Carts exist even though they have been emptied. The lifespan of a cart is 7 days since the last time it was acted upon. For example, if a cart created 6 days ago is modified, the cart lifespan is reset to 7 days.
Common request parameters¶
There are a number of optional keyword parameters which you can use to any of the afore mentioned operations.
ContentType
Specifies the format of the content in the response. Generally,
ContentType
should only be changed for REST requests when theStyle
parameter is set to an XSLT stylesheet. For example, to transform your Product Advertising API response into HTML, setContentType
totext/html
. SeeStyle
.Valid Value:
text/xml
(default),text/html
MarketplaceDomain
- Specifies the Marketplace Domain where the request will be directed. For more information, see http://docs.amazonwebservices.com/AWSECommerceService/latest/DG/index.html?MarketplaceDomainParameter.html.
MerchantId
- An optional parameter that can be used to filter search results and offer listings to only include items sold by Amazon. By default, the API will return items sold by various merchants including Amazon.
Style
Controls the format of the data returned in Product Advertising API responses.
Style
only pertains to REST requests. Set this parameter toXML
(default), to generate a pure XML response. Set this parameter to the URL of an XSLT stylesheet to have Product Advertising API transform the XML response. SeeContentType
.Valid Values: URL of an XSLT stylesheet
Validate
Prevents an operation from executing. Set the
Validate
parameter toTrue
to test your request without actually executing it. When present,Validate
must equalTrue
; the default value isFalse
. If a request is not actually executed (Validate=True
), only a subset of the errors for a request may be returned because some errors (for example,NoExactMatchesFound
) are only generated during the execution of a request.Valid Values:
True
,False
(default)Version
The version of the Product Advertising API software and WSDL to use. By default, the
2005-10-05
version is used. Alternately, specify a software version, such as2011-08-01
. For a list of valid version numbers, refer to the Product Advertising API Release Notes. Note that the latest version of Product Advertising API is not used by default.Valid Values: Valid WSDL version date, for example,
2011-08-01
. Default:2005-10-05
Note
If you want to adjust your
Version
more easily, have a look at Using a different API version.XMLEscaping
Specifies whether responses are XML-encoded in a single pass or a double pass. By default,
XMLEscaping
isSingle
, and Product Advertising API responses are encoded only once in XML. For example, if the response data includes an ampersand character (&), the character is returned in its regular XML encoding (&). IfXMLEscaping
isDouble
, the same ampersand character is XML-encoded twice (&). TheDouble
value forXMLEscaping
is useful in some clients, such as PHP, that do not decode text within XML elements.Valid Values:
Single
(default),Double
Please refer to http://docs.amazonwebservices.com/AWSECommerceService/latest/DG/index.html?CommonRequestParameters.html for an up-to-date list of parameters.