24.3. Zend_Service_Amazon
Prev | Chapter 24. Zend_Service | Next

## 24.3. Zend_Service_Amazon

### 24.3.1. Introduction

`Zend_Service_Amazon` is a simple API for using Amazon web services. `Zend_Service_Amazon` has two APIs: a more traditional one that follows Amazon's own API, and a simpler "Query API" for constructing even complex search queries easily.

`Zend_Service_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 `Zend_Service_Amazon`, you should already have an Amazon developer API key. To get a key and for more information, please visit the Amazon Web Services web site.

| Attention
Your Amazon developer API key is linked to your Amazon identity, so take appropriate measures to keep your API key private.

Example 24.4. Search Amazon Using the Traditional API

In this example, we search for PHP books at Amazon and loop through the results, printing them.

    <?php
    require_once 'Zend/Service/Amazon.php';
    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY&');
    $response = $amazon->itemSearch(array('SearchIndex' => 'Books', 'Keywords' => 'php'));
    foreach ($response as $r) {
        echo $r->Title .'<br />';
    }
    ?>

Example 24.5. 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.

    <?php
    require_once 'Zend/Service/Amazon/Query.php';
    $query = new Zend_Service_Amazon_Query('AMAZON_API_KEY');
    $query->category('Books')->Keywords('PHP');
    $results = $query->search();
    foreach ($results as $result) {
        echo $result->Title .'<br />';
    }
    ?>

### 24.3.2. Country Codes

By default, `Zend_Service_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:

Example 24.6. Choosing an Amazon Web Service Country

    <?php
    // Connect to Amazon in Japan
    require_once 'Zend/Service/Amazon.php';
    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY', 'JP');
    ?>

| Country codes
Valid country codes are: `CA`, `DE`, `FR`, `JP`, `UK`, and `US`.

### 24.3.3. 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.

Example 24.7. Looking up a Specific Amazon Item by ASIN

    <?php
    require_once 'Zend/Service/Amazon.php';
    $amazon = new Zend_Service_Amazon('AMAZON_API_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.

| Image information
To retrieve images information for your search results, you must set `ResponseGroup` option to `Medium` or `Large`.

### 24.3.4. 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:

Example 24.8. Performing Amazon Item Searches

    <?php
    require_once 'Zend/Service/Amazon.php';
    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY');
    $response = $amazon->itemSearch(array('SearchIndex' => 'Books', 'Keywords' => 'php'));
    foreach($response as $r) {
        echo $r->Title .'<br />';
    }
    ?>

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 `Zend_Service_Amazon_Query` class is an easy to use wrapper around this method.

### 24.3.5. Using the Alternative Query API

#### 24.3.5.1. Introduction

`Zend_Service_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 `Zend_Service_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:

Example 24.9. 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:

    <?php
        require_once 'Zend/Service/Amazon/Query.php';
        $query = new Zend_Service_Amazon_Query('MY_API_KEY');
        $query->Category('Books')->Keywords('PHP');
        $results = $query->search();
        foreach ($results as $result) {
            echo $result->Title .'<br />';
        }
        ?>

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.

### 24.3.6. Zend_Service_Amazon Classes

The following classes are all returned by `Zend_Service_Amazon::itemLookup()` and `Zend_Service_Amazon::itemSearch()`:

- `Zend_Service_Amazon_Item`

- `Zend_Service_Amazon_Image`

- `Zend_Service_Amazon_ResultSet`

- `Zend_Service_Amazon_OfferSet`

- `Zend_Service_Amazon_Offer`

- `Zend_Service_Amazon_SimilarProduct`

- `Zend_Service_Amazon_Accessories`

- `Zend_Service_Amazon_CustomerReview`

- `Zend_Service_Amazon_EditorialReview`

- `Zend_Service_Amazon_ListMania`

#### 24.3.6.1. Zend_Service_Amazon_Item

`Zend_Service_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.

##### 24.3.6.1.1. Zend_Service_Amazon_Item::asXML()

`string asXML();`

Return the original XML for the item

##### 24.3.6.1.2. Properties

`Zend_Service_Amazon_Item` has a number of properties directly related to their standard Amazon API counterparts.

Table 24.1. Zend_Service_Amazon_Item Properties

Name | Type | Description
--- | --- | ---
ASIN | string | Amazon Item ID
DetailPageURL | string | URL to the Items Details Page
SalesRank | string | Sales Rank for the Item
SmallImage | Zend_Service_Amazon_Image | Small Image of the Item
MediumImage | Zend_Service_Amazon_Image | Medium Image of the Item
LargeImage | Zend_Service_Amazon_Image | Large Image of the Item
Subjects | array | Item Subjects
Offers | `Zend_Service_Amazon_OfferSet` | Offer Summary and Offers for the Item
CustomerReviews | array | Customer reviews represented as an array of `Zend_Service_Amazon_CustomerReview` objects
EditorialReviews | array | Editorial reviews represented as an array of `Zend_Service_Amazon_EditorialReview` objects
SimilarProducts | array | Similar Products represented as an array of `Zend_Service_Amazon_SimilarProduct` objects
Accessories | array | Accessories for the item represented as an array of `Zend_Service_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 `Zend_Service_Amazon_ListmainList` objects
PromotionalTag | string | Item Promotional Tag

Back to Class List

#### 24.3.6.2. Zend_Service_Amazon_Image

`Zend_Service_Amazon_Image` represents a remote Image for a product.

##### 24.3.6.2.1. Properties

Table 24.2. Zend_Service_Amazon_Image Properties

Name | Type | Description
--- | --- | ---
Url | Zend_Uri | Remote URL for the Image
Height | int | The Height of the image in pixels
Width | int | The Width of the image in pixels

Back to Class List

#### 24.3.6.3. Zend_Service_Amazon_ResultSet

`Zend_Service_Amazon_ResultSet` objects are returned by Zend_Service_Amazon::itemSearch() and allow you to easily handle the multiple results returned.

| SeekableIterator
Implements the `SeekableIterator` for easy iteration (e.g. using `foreach`), as well as direct access to a specific result using `seek()`.

##### 24.3.6.3.1. Zend_Service_Amazon_ResultSet::totalResults()

`int totalResults();`

Returns the total number of results returned by the search

Back to Class List

#### 24.3.6.4. Zend_Service_Amazon_OfferSet

Each result returned by Zend_Service_Amazon::itemSearch() and Zend_Service_Amazon::itemLookup() contains a `Zend_Service_Amazon_OfferSet` object through which pricing information for the item can be retrieved.

##### 24.3.6.4.1. Properties

Table 24.3. Zend_Service_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 `Zend_Service_Amazon_Offer` objects.

Back to Class List

#### 24.3.6.5. Zend_Service_Amazon_Offer

Each offer for an item is returned as an `Zend_Service_Amazon_Offer` object.

##### 24.3.6.5.1. Zend_Service_Amazon_Offer Properties

Table 24.4. Properties

Name | Type | Description
--- | --- | ---
MerchantId | string | Merchants Amazon ID
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

Back to Class List

#### 24.3.6.6. Zend_Service_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 `Zend_Service_Amazon_SimilarProduct` object.

Each object contains the information to allow you to make sub-sequent requests to get the full information on the item.

##### 24.3.6.6.1. Properties

Table 24.5. Zend_Service_Amazon_SimilarProduct Properties

Name | Type | Description
--- | --- | ---
ASIN | string | Products Amazon Unique ID (ASIN)
Title | string | Products Title

Back to Class List

#### 24.3.6.7. Zend_Service_Amazon_Accessories

Accessories for the returned item are represented as `Zend_Service_Amazon_Accessories` objects

##### 24.3.6.7.1. Properties

Table 24.6. Zend_Service_Amazon_Accessories Properties

Name | Type | Description
--- | --- | ---
ASIN | string | Products Amazon Unique ID (ASIN)
Title | string | Products Title

Back to Class List

#### 24.3.6.8. Zend_Service_Amazon_CustomerReview

Each Customer Review is returned as a `Zend_Service_Amazon_CustomerReview` object.

##### 24.3.6.8.1. Properties

Table 24.7. Zend_Service_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

Back to Class List

#### 24.3.6.9. Zend_Service_Amazon_EditorialReview

Each items Editorial Reviews are returned as a `Zend_Service_Amazon_EditorialReview` object

##### 24.3.6.9.1. Properties

Table 24.8. Zend_Service_Amazon_EditorialReview Properties

Name | Type | Description
--- | --- | ---
Source | string | Source of the Editorial Review
Content | string | Review Content

Back to Class List

#### 24.3.6.10. Zend_Service_Amazon_Listmania

Each results List Mania List items are returned as `Zend_Service_Amazon_Listmania` objects.

##### 24.3.6.10.1. Properties

Table 24.9. Zend_Service_Amazon_Listmania Properties

Name | Type | Description
--- | --- | ---
ListId | string | List ID
ListName | string | List Name

Back to Class List

Prev | Up | Next
24.2. Zend_Service_Akismet | Home | 24.4. Zend_Service_Flickr