Sebastian Rahlf committed 5160329

Tweaked introductory text a bit.

Comments (0)

Files changed (2)


-Basic usage
+.. _getting-started:
+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`_.
+.. 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:
+    2011-08-01/DG/Welcome.html?r=4324
 Basic setup
 If you haven't done so already, create a file ``~/.amazon-product-api``
-(``C:\Users\You\.amazon-product-api`` if your on Windows) and paste the
+(``C:\Users\You\.amazon-product-api`` if you're on Windows) and paste the
 following content into it::
     api = API(locale='us')
     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
+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 :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:
+    AWSECommerceService/latest/DG/CHAP_LocaleConsiderations.html
+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 node.Items.Item:
+    for book in items:
         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:
-__ lxml.objectify_
+.. _dealing-with-errors:
 Dealing with errors
 A list of exceptions can be found in :ref:`error-handling`.
-More information on the API
-* Amazon Product Advertising API Best Practices: 


+.. _operations: