Getting started

In order to use this API you’ll obviously need an Amazon Associates Web Service account for which you must register with Amazon. Each account contains an AWSAccessKeyId and a SecretKey. As of API version 2011-08-01 you will also need to register for an AssociateTag.


It is assumed that you know what the Amazon Product Advertising API does. If you are unsure, read their developer guide (particularly the section Introduction to the Product Advertising API.

Basic setup

If you haven’t done so already, create a file ~/.amazon-product-api (C:\Users\You\.amazon-product-api if you’re on Windows) and paste the following content into it:

access_key = <your access key>
secret_key = <your secret key>
associate_tag = <your associate id>

Of course, you’ll need to fill in the appropriate values! More information on how to configure the module can be found later on.

Your first API request

Here is an example how to use the API to search for books of a certain publisher.

api = API(locale='us')
items = api.item_search('Books', Publisher="O'Reilly")

So what happens here? First you initialised your API wrapper to use There are, of course, other locales available should you wish to use a different one. For instance, locale='de' will cause requests to be sent to (Germany).

Afterwards you called the API operation ItemSearch to get a list of all books that where published by O’Reilly. Now method item_search does several things at once for you:

  1. It turns all your parameters into a validly signed URL and sends a request.
  2. The returned XML document is parsed and if it contains any error message, the appropriate Python exception is raised (see Dealing with errors).
  3. Amazon itself provides their results spread over several pages. If you were to do this manually you would have to make several calls. To make things easier for you item_search() will iterate over all availabe results (see Result pagination for more information).

You can now iterate over the items and will get a number of parsed XML nodes (by default and if available lxml.objectify is used). With it you can access all elements and attributes in a Pythonic way:

# get all books from result set and
# print author and title
for book in items:
    print '%s: "%s"' % (book.ItemAttributes.Author,

Please refer to the lxml.objectify documentation for more details. If you cannot/will not use lxml, see Result processing for alternatives.

You can find more API operations later in Operations.

Dealing with errors

One of the advatages of using this wrapper is that all error messages from Amazon will raise Python exceptions with meaningful messages.

    node = api.similarity_lookup('0451462009', '0718155157')
    # ...
except NoSimilarityForASIN, e:
    print 'There is no book similar to %s!' % e.args[0]
except AWSError, e:
    print 'Amazon complained about yout request!'
    print e.code
    print e.msg

A list of exceptions can be found in Error handling.