.. _zendservice.amazon:
ZendService\Amazon
===================
.. _zendservice.amazon.introduction:
Introduction
------------
``ZendService\Amazon`` is a simple *API* for using Amazon web services. ``ZendService\Amazon`` has two *API*\ s:
a more traditional one that follows Amazon's own *API*, and a simpler "Query *API*" for constructing even complex
search queries easily.
``ZendService\Amazon`` enables developers to retrieve information appearing throughout Amazon.com web sites
directly through the Amazon Web Services *API*. Examples include:
- Store item information, such as images, descriptions, pricing, and more
- Customer and editorial reviews
- Similar products and accessories
- Amazon.com offers
- ListMania lists
In order to use ``ZendService\Amazon``, you should already have an Amazon developer *API* key as well as a secret
key. To get a key and for more information, please visit the `Amazon Web Services`_ web site. As of August 15th,
2009 you can only use the Amazon Product Advertising *API* through ``ZendService\Amazon``, when specifying the
additional secret key.
.. note::
**Attention**
Your Amazon developer *API* and secret keys are linked to your Amazon identity, so take appropriate measures to
keep them private.
.. _zendservice.amazon.introduction.example.itemsearch:
.. rubric:: Search Amazon Using the Traditional API
In this example, we search for *PHP* books at Amazon and loop through the results, printing them.
.. code-block:: php
:linenos:
$amazon = new ZendService\Amazon\Amazon('AMAZON_API_KEY', 'US', 'AMAZON_SECRET_KEY');
$results = $amazon->itemSearch(array('SearchIndex' => 'Books',
'Keywords' => 'php'));
foreach ($results as $result) {
echo $result->Title . '
';
}
.. _zendservice.amazon.introduction.example.query_api:
.. rubric:: Search Amazon Using the Query API
Here, we also search for *PHP* books at Amazon, but we instead use the Query *API*, which resembles the Fluent
Interface design pattern.
.. code-block:: php
:linenos:
$query = new ZendService\Amazon\Query('AMAZON_API_KEY',
'US',
'AMAZON_SECRET_KEY');
$query->category('Books')->Keywords('PHP');
$results = $query->search();
foreach ($results as $result) {
echo $result->Title . '
';
}
.. _zendservice.amazon.countrycodes:
Country Codes
-------------
By default, ``ZendService\Amazon`` connects to the United States ("*US*") Amazon web service. To connect from a
different country, simply specify the appropriate country code string as the second parameter to the constructor:
.. _zendservice.amazon.countrycodes.example.country_code:
.. rubric:: Choosing an Amazon Web Service Country
.. code-block:: php
:linenos:
// Connect to Amazon in Japan
$amazon = new ZendService\Amazon\Amazon('AMAZON_API_KEY', 'JP', 'AMAZON_SECRET_KEY');
.. note::
**Country codes**
Valid country codes are: *CA*, *DE*, *FR*, *JP*, *UK*, and *US*.
.. _zendservice.amazon.itemlookup:
Looking up a Specific Amazon Item by ASIN
-----------------------------------------
The ``itemLookup()`` method provides the ability to fetch a particular Amazon item when the *ASIN* is known.
.. _zendservice.amazon.itemlookup.example.asin:
.. rubric:: Looking up a Specific Amazon Item by ASIN
.. code-block:: php
:linenos:
$amazon = new ZendService\Amazon\Amazon('AMAZON_API_KEY', 'US', 'AMAZON_SECRET_KEY');
$item = $amazon->itemLookup('B0000A432X');
The ``itemLookup()`` method also accepts an optional second parameter for handling search options. For full
details, including a list of available options, please see the `relevant Amazon documentation`_.
.. note::
**Image information**
To retrieve images information for your search results, you must set *ResponseGroup* option to *Medium* or
*Large*.
.. _zendservice.amazon.itemsearch:
Performing Amazon Item Searches
-------------------------------
Searching for items based on any of various available criteria are made simple using the ``itemSearch()`` method,
as in the following example:
.. _zendservice.amazon.itemsearch.example.basic:
.. rubric:: Performing Amazon Item Searches
.. code-block:: php
:linenos:
$amazon = new ZendService\Amazon\Amazon('AMAZON_API_KEY', 'US', 'AMAZON_SECRET_KEY');
$results = $amazon->itemSearch(array('SearchIndex' => 'Books',
'Keywords' => 'php'));
foreach ($results as $result) {
echo $result->Title . '
';
}
.. _zendservice.amazon.itemsearch.example.responsegroup:
.. rubric:: Using the ResponseGroup Option
The *ResponseGroup* option is used to control the specific information that will be returned in the response.
.. code-block:: php
:linenos:
$amazon = new ZendService\Amazon\Amazon('AMAZON_API_KEY', 'US', 'AMAZON_SECRET_KEY');
$results = $amazon->itemSearch(array(
'SearchIndex' => 'Books',
'Keywords' => 'php',
'ResponseGroup' => 'Small,ItemAttributes,Images,SalesRank,Reviews,' .
'EditorialReview,Similarities,ListmaniaLists'
));
foreach ($results as $result) {
echo $result->Title . '
';
}
The ``itemSearch()`` method accepts a single array parameter for handling search options. For full details,
including a list of available options, please see the `relevant Amazon documentation`_
.. tip::
The :ref:`ZendService\Amazon\Query ` class is an easy to use wrapper around this
method.
.. _zendservice.amazon.query:
Using the Alternative Query API
-------------------------------
.. _zendservice.amazon.query.introduction:
Introduction
^^^^^^^^^^^^
``ZendService\Amazon\Query`` provides an alternative *API* for using the Amazon Web Service. The alternative *API*
uses the Fluent Interface pattern. That is, all calls can be made using chained method calls. (e.g.,
*$obj->method()->method2($arg)*)
The ``ZendService\Amazon\Query`` *API* uses overloading to easily set up an item search and then allows you to
search based upon the criteria specified. Each of the options is provided as a method call, and each method's
argument corresponds to the named option's value:
.. _zendservice.amazon.query.introduction.example.basic:
.. rubric:: Search Amazon Using the Alternative Query API
In this example, the alternative query *API* is used as a fluent interface to specify options and their respective
values:
.. code-block:: php
:linenos:
$query = new ZendService\Amazon\Query('MY_API_KEY', 'US', 'AMAZON_SECRET_KEY');
$query->Category('Books')->Keywords('PHP');
$results = $query->search();
foreach ($results as $result) {
echo $result->Title . '
';
}
This sets the option *Category* to "Books" and *Keywords* to "PHP".
For more information on the available options, please refer to the `relevant Amazon documentation`_.
.. _zendservice.amazon.classes:
ZendService\Amazon Classes
---------------------------
The following classes are all returned by :ref:`ZendService\Amazon::itemLookup() `
and :ref:`ZendService\Amazon::itemSearch() `:
- :ref:`ZendService\Amazon\Item `
- :ref:`ZendService\Amazon\Image `
- :ref:`ZendService\Amazon\ResultSet `
- :ref:`ZendService\Amazon\OfferSet `
- :ref:`ZendService\Amazon\Offer `
- :ref:`ZendService\Amazon\SimilarProduct `
- :ref:`ZendService\Amazon\Accessories `
- :ref:`ZendService\Amazon\CustomerReview `
- :ref:`ZendService\Amazon\EditorialReview `
- :ref:`ZendService\Amazon\ListMania `
.. _zendservice.amazon.classes.item:
ZendService\Amazon\Item
^^^^^^^^^^^^^^^^^^^^^^^^
``ZendService\Amazon\Item`` is the class type used to represent an Amazon item returned by the web service. It
encompasses all of the items attributes, including title, description, reviews, etc.
.. _zendservice.amazon.classes.item.asxml:
ZendService\Amazon\Item::asXML()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
string:``asXML()``
Return the original *XML* for the item
.. _zendservice.amazon.classes.item.properties:
Properties
^^^^^^^^^^
``ZendService\Amazon\Item`` has a number of properties directly related to their standard Amazon *API*
counterparts.
.. _zendservice.amazon.classes.item.properties.table-1:
.. table:: ZendService\Amazon\Item Properties
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|Name |Type |Description |
+================+============================+===========================================================================================+
|ASIN |string |Amazon Item ID |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|DetailPageURL |string |URL to the Items Details Page |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|SalesRank |int |Sales Rank for the Item |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|SmallImage |ZendService\Amazon\Image |Small Image of the Item |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|MediumImage |ZendService\Amazon\Image |Medium Image of the Item |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|LargeImage |ZendService\Amazon\Image |Large Image of the Item |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|Subjects |array |Item Subjects |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|Offers |ZendService\Amazon\OfferSet|Offer Summary and Offers for the Item |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|CustomerReviews |array |Customer reviews represented as an array of ZendService\Amazon\CustomerReview objects |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|EditorialReviews|array |Editorial reviews represented as an array of ZendService\Amazon\EditorialReview objects |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|SimilarProducts |array |Similar Products represented as an array of ZendService\Amazon\SimilarProduct objects |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|Accessories |array |Accessories for the item represented as an array of ZendService\Amazon\Accessories objects|
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|Tracks |array |An array of track numbers and names for Music CDs and DVDs |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|ListmaniaLists |array |Item related Listmania Lists as an array of ZendService\Amazon\ListmaniaList objects |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
|PromotionalTag |string |Item Promotional Tag |
+----------------+----------------------------+-------------------------------------------------------------------------------------------+
:ref:`Back to Class List `
.. _zendservice.amazon.classes.image:
ZendService\Amazon\Image
^^^^^^^^^^^^^^^^^^^^^^^^^
``ZendService\Amazon\Image`` represents a remote Image for a product.
.. _zendservice.amazon.classes.image.properties:
Properties
^^^^^^^^^^
.. _zendservice.amazon.classes.image.properties.table-1:
.. table:: ZendService\Amazon\Image Properties
+------+------------+---------------------------------+
|Name |Type |Description |
+======+============+=================================+
|Url |Zend\Uri\Uri|Remote URL for the Image |
+------+------------+---------------------------------+
|Height|int |The Height of the image in pixels|
+------+------------+---------------------------------+
|Width |int |The Width of the image in pixels |
+------+------------+---------------------------------+
:ref:`Back to Class List `
.. _zendservice.amazon.classes.resultset:
ZendService\Amazon\ResultSet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``ZendService\Amazon\ResultSet`` objects are returned by :ref:`ZendService\Amazon::itemSearch()
` and allow you to easily handle the multiple results returned.
.. note::
**SeekableIterator**
Implements the *SeekableIterator* for easy iteration (e.g. using *foreach*), as well as direct access to a
specific result using ``seek()``.
.. _zendservice.amazon.classes.resultset.totalresults:
ZendService\Amazon\ResultSet::totalResults()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
int:``totalResults()``
Returns the total number of results returned by the search
:ref:`Back to Class List `
.. _zendservice.amazon.classes.offerset:
ZendService\Amazon\OfferSet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Each result returned by :ref:`ZendService\Amazon::itemSearch() ` and
:ref:`ZendService\Amazon::itemLookup() ` contains a
``ZendService\Amazon\OfferSet`` object through which pricing information for the item can be retrieved.
.. _zendservice.amazon.classes.offerset.parameters:
Properties
^^^^^^^^^^
.. _zendservice.amazon.classes.offerset.parameters.table-1:
.. table:: ZendService\Amazon\OfferSet Properties
+----------------------+------+--------------------------------------------------------------+
|Name |Type |Description |
+======================+======+==============================================================+
|LowestNewPrice |int |Lowest Price for the item in "New" condition |
+----------------------+------+--------------------------------------------------------------+
|LowestNewPriceCurrency|string|The currency for the LowestNewPrice |
+----------------------+------+--------------------------------------------------------------+
|LowestOldPrice |int |Lowest Price for the item in "Used" condition |
+----------------------+------+--------------------------------------------------------------+
|LowestOldPriceCurrency|string|The currency for the LowestOldPrice |
+----------------------+------+--------------------------------------------------------------+
|TotalNew |int |Total number of "new" condition available for the item |
+----------------------+------+--------------------------------------------------------------+
|TotalUsed |int |Total number of "used" condition available for the item |
+----------------------+------+--------------------------------------------------------------+
|TotalCollectible |int |Total number of "collectible" condition available for the item|
+----------------------+------+--------------------------------------------------------------+
|TotalRefurbished |int |Total number of "refurbished" condition available for the item|
+----------------------+------+--------------------------------------------------------------+
|Offers |array |An array of ZendService\Amazon\Offer objects. |
+----------------------+------+--------------------------------------------------------------+
:ref:`Back to Class List `
.. _zendservice.amazon.classes.offer:
ZendService\Amazon\Offer
^^^^^^^^^^^^^^^^^^^^^^^^^
Each offer for an item is returned as an ``ZendService\Amazon\Offer`` object.
.. _zendservice.amazon.classes.offer.properties:
ZendService\Amazon\Offer Properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _zendservice.amazon.classes.offer.properties.table-1:
.. table:: Properties
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|Name |Type |Description |
+===============================+=======+==========================================================================================+
|MerchantId |string |Merchants Amazon ID |
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|MerchantName |string |Merchants Amazon Name. Requires setting the ResponseGroup option to OfferFull to retrieve.|
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|GlancePage |string |URL for a page with a summary of the Merchant |
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|Condition |string |Condition of the item |
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|OfferListingId |string |ID of the Offer Listing |
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|Price |int |Price for the item |
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|CurrencyCode |string |Currency Code for the price of the item |
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|Availability |string |Availability of the item |
+-------------------------------+-------+------------------------------------------------------------------------------------------+
|IsEligibleForSuperSaverShipping|boolean|Whether the item is eligible for Super Saver Shipping or not |
+-------------------------------+-------+------------------------------------------------------------------------------------------+
:ref:`Back to Class List `
.. _zendservice.amazon.classes.similarproduct:
ZendService\Amazon\SimilarProduct
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When searching for items, Amazon also returns a list of similar products that the searcher may find to their
liking. Each of these is returned as a ``ZendService\Amazon\SimilarProduct`` object.
Each object contains the information to allow you to make sub-sequent requests to get the full information on the
item.
.. _zendservice.amazon.classes.similarproduct.properties:
Properties
^^^^^^^^^^
.. _zendservice.amazon.classes.similarproduct.properties.table-1:
.. table:: ZendService\Amazon\SimilarProduct Properties
+-----+------+--------------------------------+
|Name |Type |Description |
+=====+======+================================+
|ASIN |string|Products Amazon Unique ID (ASIN)|
+-----+------+--------------------------------+
|Title|string|Products Title |
+-----+------+--------------------------------+
:ref:`Back to Class List `
.. _zendservice.amazon.classes.accessories:
ZendService\Amazon\Accessories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Accessories for the returned item are represented as ``ZendService\Amazon\Accessories`` objects
.. _zendservice.amazon.classes.accessories.properties:
Properties
^^^^^^^^^^
.. _zendservice.amazon.classes.accessories.properties.table-1:
.. table:: ZendService\Amazon\Accessories Properties
+-----+------+--------------------------------+
|Name |Type |Description |
+=====+======+================================+
|ASIN |string|Products Amazon Unique ID (ASIN)|
+-----+------+--------------------------------+
|Title|string|Products Title |
+-----+------+--------------------------------+
:ref:`Back to Class List `
.. _zendservice.amazon.classes.customerreview:
ZendService\Amazon\CustomerReview
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Each Customer Review is returned as a ``ZendService\Amazon\CustomerReview`` object.
.. _zendservice.amazon.classes.customerreview.properties:
Properties
^^^^^^^^^^
.. _zendservice.amazon.classes.customerreview.properties.table-1:
.. table:: ZendService\Amazon\CustomerReview Properties
+------------+------+----------------------------------+
|Name |Type |Description |
+============+======+==================================+
|Rating |string|Item Rating |
+------------+------+----------------------------------+
|HelpfulVotes|string|Votes on how helpful the review is|
+------------+------+----------------------------------+
|CustomerId |string|Customer ID |
+------------+------+----------------------------------+
|TotalVotes |string|Total Votes |
+------------+------+----------------------------------+
|Date |string|Date of the Review |
+------------+------+----------------------------------+
|Summary |string|Review Summary |
+------------+------+----------------------------------+
|Content |string|Review Content |
+------------+------+----------------------------------+
:ref:`Back to Class List `
.. _zendservice.amazon.classes.editorialreview:
ZendService\Amazon\EditorialReview
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Each items Editorial Reviews are returned as a ``ZendService\Amazon\EditorialReview`` object
.. _zendservice.amazon.classes.editorialreview.properties:
Properties
^^^^^^^^^^
.. _zendservice.amazon.classes.editorialreview.properties.table-1:
.. table:: ZendService\Amazon\EditorialReview Properties
+-------+------+------------------------------+
|Name |Type |Description |
+=======+======+==============================+
|Source |string|Source of the Editorial Review|
+-------+------+------------------------------+
|Content|string|Review Content |
+-------+------+------------------------------+
:ref:`Back to Class List `
.. _zendservice.amazon.classes.listmania:
ZendService\Amazon\Listmania
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Each results List Mania List items are returned as ``ZendService\Amazon\Listmania`` objects.
.. _zendservice.amazon.classes.listmania.properties:
Properties
^^^^^^^^^^
.. _zendservice.amazon.classes.listmania.properties.table-1:
.. table:: ZendService\Amazon\Listmania Properties
+--------+------+-----------+
|Name |Type |Description|
+========+======+===========+
|ListId |string|List ID |
+--------+------+-----------+
|ListName|string|List Name |
+--------+------+-----------+
:ref:`Back to Class List `
.. _`Amazon Web Services`: http://aws.amazon.com/
.. _`relevant Amazon documentation`: http://www.amazon.com/gp/aws/sdk/main.html/102-9041115-9057709?s=AWSEcommerceService&v=2011-08-01&p=ApiReference/ItemSearchOperation