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`_.
+.. note:: 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*.
+.. _developer guide: http://docs.amazonwebservices.com/AWSECommerceService/
If you haven't done so already, create a file ``~/.amazon-product-api``
-(``C:\Users\You\.amazon-product-api`` if you
r on Windows) and paste the
+(``C:\Users\You\.amazon-product-api`` if you on Windows) and paste the
following content into it::
items = api.item_search('Books', Publisher="O'Reilly")
-The ``node`` object returned is a `lxml.objectified`__ element. All its
-attributes can be accessed the pythonic way::
- # .pyval will convert the node content into int here
- total_results = node.Items.TotalResults.pyval
- total_pages = node.Items.TotalPages.pyval
+So what happens here? First you initialised your API wrapper to use Amazon.com.
+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
+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
+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 :ref:`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 :meth:`item_search` will iterate over all availabe results
+ (see :ref:`pagination` for more information).
+.. _other locales available: http://docs.amazonwebservices.com/
+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
- for book in
print '%s: "%s"' % (book.ItemAttributes.Author,
-Please refer to the `lxml.objectify`_ documentation for more details.
+Please refer to the `lxml.objectify`_ documentation for more details. If you
+cannot/will not use lxml, see :ref:`pagination` for alternatives.
+You can find more API operations later in :ref:`operations`.
.. _lxml.objectify: http://codespeak.net/lxml/objectify.html
A list of exceptions can be found in :ref:`error-handling`.
-More information on the API
-* Amazon Product Advertising API Best Practices: