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.

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. When condition 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 an item_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 maximum ItemPage number that can be returned is 400. An error is returned if you try to access higher numbered pages. If you do not include ItemPage 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 and Keywords 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 the BrowseNode 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)' % (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.

Results spanning multiple pages will all be subsequently retrieved when you iterate over them. See Result pagination for more details.

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, including New, Used, Collectible, and Refurbished.

  • 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 or Collectible. 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 an browse_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 an item_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 a CartItemId and accessible only by that value. That is, in subsequent requests, an item in a cart cannot be accessed by its ListItemId and ASIN, or OfferListingId. CartItemId is returned by cart_create(), cart_get(), and cart_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, use cart_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 are SaveForLaterItems.

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 than ValueError.

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, including SavedForLater 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 and HMAC values, which are returned in the cart_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 the URLEncodedHMAC value for the HMAC parameter.

cart_get() does not work after the customer has used the PurchaseURL to either purchase the items or merge them with the items in their Amazon cart.

If the associated cart_create() request specified an AssociateTag, all cart_get() requests must also include a value for AssociateTag 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 the cart_modify() operation.

You add an item to a cart by specifying the item’s OfferListingId, or ASIN and ListItemId. Once in a cart, an item can only be identified by its CartItemId. That is, an item in a cart cannot be accessed by its ASIN or OfferListingId. CartItemId is returned by cart_create(), cart_get(), and cart_add().

To add items to a cart, you must specify the cart using the CartId and HMAC values, which are returned by the cart_create() operation.

If the associated cart_create() request specified an AssociateTag, all cart_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 than ValueError.

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 the SaveForLater 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 the cart_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 the URLEncodedHMAC 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, use cart_modify() to add new items to a cart.

If the associated cart_create() request specified an AssociateTag, all cart_modify() requests must also include a value for Associate Tag otherwise the request will fail.

Changed in version 0.2.8: Will raise ParameterOutOfRange or MissingParameters rather than ValueError.

API.cart_clear(cart_id, hmac, **params)

The cart_clear() operation enables you to remove all of the items in a remote shopping cart, including SavedForLater items. To remove only some of the items in a cart or to reduce the quantity of one or more items, use cart_modify().

To delete all of the items from a remote shopping cart, you must specify the cart using the CartId and HMAC values, which are returned by the cart_create() operation. A value similar to the 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 the U``RLEncodedHMAC`` value for the HMAC parameter.

cart_clear() does not work after the customer has used the PurchaseURL 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 the Style parameter is set to an XSLT stylesheet. For example, to transform your Product Advertising API response into HTML, set ContentType to text/html. See Style.

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 to XML (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. See ContentType.

Valid Values: URL of an XSLT stylesheet

Validate

Prevents an operation from executing. Set the Validate parameter to True to test your request without actually executing it. When present, Validate must equal True; the default value is False. 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 as 2011-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 is Single, 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 (&). If XMLEscaping is Double, the same ampersand character is XML-encoded twice (&). The Double value for XMLEscaping 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.